Vizro Dash Components

Vizro Dash Components are used by the Vizro framework but can be used in a pure Dash app. Use as import vizro_dash_components as vdc.

See the example Dash app and its live demo on PyCafe for a full demo of all components.

Installation

pip install vizro-dash-components

Components

Markdown

Based on dcc.Markdown, with identical properties. Renders Markdown content with syntax-highlighted code blocks via dmc.CodeHighlight and dmc.InlineCodeHighlight. Requires a dmc.MantineProvider wrapper.

import dash_mantine_components as dmc
import vizro_dash_components as vdc
from dash import Dash

app = Dash(__name__)

app.layout = dmc.MantineProvider(
    vdc.Markdown(
        id="my-markdown",
        children="""
            # Hello World

            ```python
            print("Hello, World!")
            ```
            """,
    )
)

if __name__ == "__main__":
    app.run()

Cascader

Hierarchical cascading dropdown inspired by Ant Design Cascader and fac.AntdCascader. Users navigate a tree of options via side-by-side panels and select leaves (each returned as its full root-to-leaf path). Supports single-select and multi-select. It accepts all the same arguments as dcc.Dropdown (for example className, style, clearable, searchable, search_value, placeholder, disabled, multi, optionHeight, maxHeight, debounce, closeOnSelect, labels, and persistence props) and is built to visually match it. Use help(vdc.Cascader) for the full list.

options format

options for dcc.Dropdown describes a flat list and can be given in two different formats: a shorthand and an explicit option dict. options for vdc.Cascader describes a tree and can similarly be given in two different formats:

1. Shorthand

   • dcc.Dropdown: a list, for example ["New York City", "Montreal"].
   • vdc.Cascader: a nested dict/list, for example {"USA": ["New York City", "Boston"], "Canada": ["Toronto", "Montreal"]}.

2. Explicit option dicts

   • dcc.Dropdown: a list of dicts, each with label and value, plus optional keys such as disabled and search.
   • vdc.Cascader: a list of dicts, each with label and value, plus optional keys such as disabled and search. Parents also have children, a list of child dicts; leaves omit children.

The vdc.Cascader component’s value is the full root-to-leaf path: a list of node values from the root down to the selected leaf, for example ["Europe", "France", "Paris"]. When multi=True it is a list of such paths, for example [["Europe", "France", "Paris"], ["Asia", "Japan", "Tokyo"]]. Because paths are used, duplicate leaf labels in different branches (for example a "Portland" under both "Oregon" and "Maine") are addressed unambiguously.

from dash import Dash, Input, Output, html
import vizro_dash_components as vdc

OPTIONS = {
    "Asia": {
        "Japan": ["Tokyo", "Osaka", "Kyoto"],
        "China": ["Beijing", "Shanghai", "Guangzhou"],
    },
    "Europe": {
        "France": ["Paris", "Lyon", "Marseille"],
        "Germany": ["Berlin", "Munich", "Hamburg"],
    },
}

# Same tree in explicit form.
# label doesn't need to match value any more.
# Optional on any dict: disabled, search.
# OPTIONS = [
#     {
#         "label": "Asia",
#         "value": "Asia",
#         "children": [
#             {
#                 "label": "Japan",
#                 "value": "Japan",
#                 "children": [
#                     {"label": "Tokyo", "value": "Tokyo"},
#                     {"label": "Osaka", "value": "Osaka"},
#                     {"label": "Kyoto", "value": "Kyoto"},
#                 ],
#             },
#             {
#                 "label": "China",
#                 "value": "China",
#                 "children": [
#                     {"label": "Beijing", "value": "Beijing"},
#                     {"label": "Shanghai", "value": "Shanghai"},
#                     {"label": "Guangzhou", "value": "Guangzhou"},
#                 ],
#             },
#         ],
#     },
#     ... similarly for Europe
# ]

app = Dash(__name__)
app.layout = [
    vdc.Cascader(id="regions", options=OPTIONS, placeholder="Select a city..."),
    html.Div(id="out"),
]


@app.callback(Output("out", "children"), Input("regions", "value"))
def show(value):
    # `value` is the full path, for example ["Asia", "Japan", "Tokyo"].
    return f"Selected path: {value!r}"


if __name__ == "__main__":
    app.run()

Development

Contributor workflows (Hatch, npm, regenerating vizro_dash_components/) are documented in AGENTS.md (same content as CLAUDE.md for Claude Code).