Skip to content

Vizro for LLMs

This page is a single-file cheatsheet for LLMs and coding agents. It restates only what an agent needs to write correct Vizro code in one pass, and links out to canonical reference for everything else. Do not duplicate content from linked pages here — follow the links.

Minimum runnable app

Five lines of Python produce a running Vizro dashboard:

import vizro.models as vm
import vizro.plotly.express as px
from vizro import Vizro

Vizro().build(vm.Dashboard(pages=[vm.Page(title="Iris", components=[vm.Graph(figure=px.scatter(px.data.iris(), x="sepal_length", y="sepal_width", color="species"))])])).run()

Longer walk-through: quickstart tutorial.

Model index (vizro.models, alias vm)

Every dashboard is a tree of these models. See the full model reference for API docs; the user-guide link explains when to reach for each one.

Model One-liner Guide
Dashboard Top-level model. Combines pages, navigation and theme. Dashboard
Page A single page. Holds components, controls, layout. Page
Container Nested section with its own layout, style, or scoped controls. Container
Tabs Switch between several Containers sharing screen space. Tabs
Grid Default row/column grid layout. Layouts
Flex Flexible-box layout. Layouts
Layout Deprecated alias for Grid. Prefer Grid in new code. Deprecations
Graph Plotly Express or custom Plotly chart. Graph
AgGrid Dash AG Grid (recommended for tables). Table
Table Dash DataTable. Table
Figure Any reactive Dash component (includes built-in KPI cards). Figure
Card Bordered Markdown callout or navigation tile. Card
Text Plain, unstyled Markdown text. Text
Button Trigger an action, submit a form, or navigate. Button
Tooltip Icon that reveals contextual Markdown help; used as a component's description. (See per-component description in user guides.)
Filter Filter that targets one or more components on a column value. Filters
Parameter Override a function argument on target components. Parameters
ControlGroup Group related controls in the sidebar. Controls
Dropdown Single/multi-select dropdown selector. Selectors
Checklist Multi-select checkbox group selector. Selectors
RadioItems Single-select radio button selector. Selectors
Switch Boolean toggle selector. Selectors
Slider Single numeric slider. Selectors
RangeSlider Numeric range slider. Selectors
DatePicker Date / date-range picker. Selectors
TimePicker Time / time-range picker. Selectors
DateTimePicker Combined date-and-time / date-and-time-range picker for datetime columns. Selectors
Cascader Cascading multi-level selector. Selectors
Navigation Dashboard navigation model. Navigation
NavBar Icon sidebar or horizontal bar of NavLinks. Navigation
NavLink Single icon-linked entry in a NavBar. Navigation
Accordion Grouped collapsible page list; default sidebar navigation. Navigation
Action Wraps a callable with function, inputs, outputs. Actions
VizroBaseModel Base class for custom components. Custom components

Built-in actions (vizro.actions, alias va)

Use these instead of writing a custom action wherever the built-in fits.

Action Purpose Guide
va.export_data() Export filtered data of targeted components to CSV or XLSX. Handle data
va.set_control() Set a Filter or Parameter value from a graph or table click, row selection, or another source component. Graph and table interactions
va.filter_interaction() Legacy alias for cross-filter behavior. Prefer va.set_control in new code. Graph and table interactions
va.show_notification() Show a toast notification. Notifications
va.update_notification() Update an already-visible toast (progress, success, error). Notifications

Selector auto-selection

Filter(column=...) picks a selector from the column dtype if selector is not set. Override by passing an explicit selector. Parameter always requires an explicit selector (it does not auto-select based on dtype).

Column dtype Default selector
numerical RangeSlider
categorical (object, string, cat) Dropdown (multi-select)
date / datetime DatePicker
time TimePicker
boolean Switch
hierarchical Cascader

See filters and selectors for the full rules, disallowed combinations, and how to make dynamic filter options static.

@capture decorator matrix

Every user-supplied callable that goes into a Vizro model must be wrapped with @capture(mode) from vizro.models.types.

Mode Wraps Used in Guide
@capture("graph") A function that returns a Plotly Figure. Graph(figure=...) Custom charts
@capture("table") A function that returns a Dash DataTable or AG Grid. Table(figure=...) or AgGrid(figure=...) Custom tables
@capture("figure") A function that returns any Dash component. Figure(figure=...) Custom figures
@capture("action") A function that runs on user interaction and returns outputs. vm.Action(function=your_fn(...)) Custom actions

Every @capture-decorated function receives its first positional argument as data:

  • @capture("graph"|"table"|"figure") → first argument is a data_frame: pandas.DataFrame.
  • @capture("action") → arguments are the values of the referenced Vizro model inputs; returns are mapped to the referenced outputs.

What only works in Python configuration

The following features cannot be expressed in a YAML or JSON dashboard configuration. If a task requires any of them, you must use the Python vm.* API.

  1. Custom components subclassing VizroBaseModel. See custom components.
  2. Custom actions wrapped with @capture("action"). See custom actions.
  3. Model.add_type(field_name, new_type) to widen a discriminated-union field for a custom component. See custom components.
  4. Custom dashboard headers or overrides (any argument that takes a Dash / dbc Python object rather than a serializable dict).
  5. Registration of CapturedCallables (@capture("graph"|"table"|"figure"|"action") decorators, custom plotly functions passed to Graph.figure, etc.). YAML and JSON can only reference registered names.

Top errors and fixes

Error Cause Fix
DuplicateIDError: Model with id=<X> already exists. Models must have a unique id across the whole dashboard. You re-ran the notebook or script without clearing the model registry, so Vizro sees two instances of the same id. Restart the kernel, or add from vizro import Vizro; Vizro._reset() at the top of the cell. See notebook workflow.
KeyError: Data source "<name>" does not exist. when running a YAML/JSON dashboard. YAML/JSON only reference data sources by name; the Python entry point did not register the data in the data manager. Before parsing the config, register data: from vizro.managers import data_manager; data_manager["<name>"] = my_dataframe. See reference by name.
ValueError: A callable of mode "..." has been provided. Please wrap it inside "vm.<Model>(figure=<callable>(...))". You passed a @capture-decorated callable to the wrong model field. Wrap it in the matching model: Graph(figure=chart(...)) for @capture("graph"), etc. See the decorator matrix.
pydantic_core.ValidationError mentioning discriminator or Input should be a valid dictionary for a custom component. The custom subclass has not been registered with add_type on the parent model's field. Call ParentModel.add_type("field_name", MyCustomClass) before instantiating. See custom components.
AttributeError: 'DataFrame' object has no attribute 'cache_arguments' (or similar cache-only errors on a data source). You called a cache-only method on data supplied directly as a DataFrame; caching applies only to registered dynamic data. Register the data source as a callable in data_manager and configure data_manager.cache. See configure cache.

Machine-readable schema

A JSON Schema of the full dashboard configuration is published per Vizro version in the repo:

For background on how the schema relates to the Python models and where its limits are, see the schema explanation.

Where to go next