---

name: charts-and-figures description: "Choose, author, and troubleshoot Vizro charts, figures, tables, and visual-vocabulary patterns with Plotly/Vizro APIs." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

Charts and Figures

Use this sub-skill when the task asks what chart to use, how to write a Vizro/Plotly figure, how to attach a figure/table to a dashboard, or how to debug visual output.

Route elsewhere when the task is mainly about:

• Dashboard/page skeleton: ../core-dashboard-build/SKILL.md.
• Filters/data/actions around a figure: ../core-components-data-actions/SKILL.md.
• Deprecated AI chart-agent code: ../legacy-ai-chart-agent/SKILL.md.

Preferred authoring pattern

Use Vizro's Plotly Express wrappers for standard charts:

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

fig = px.scatter(
    px.data.iris(),
    x="sepal_width",
    y="sepal_length",
    color="species",
)

page = vm.Page(title="Iris", components=[vm.Graph(figure=fig)])

When users supply data and a visual goal, first decide chart semantics, then write code:

1. Identify measures, dimensions, time fields, categorical fields, and intended comparison.
2. Choose chart type from visual-vocabulary principles.
3. Produce a small Plotly/Vizro snippet using explicit column names.
4. Wrap it in vm.Graph or the relevant table/grid component.
5. Add filters/selectors only after the base figure works.

Chart selection heuristics

• Time trend: line/area; use bars only for few discrete periods.
• Category comparison: bar/column; sort intentionally.
• Distribution: histogram/box/violin depending on whether the user needs bins, summary, or group comparison.
• Relationship/correlation: scatter/bubble; add color/facet only when it clarifies.
• Part-to-whole: stacked bar or treemap/sunburst for hierarchy; avoid pie for many categories.
• Geospatial: map only when location is the analytic dimension; otherwise avoid decorative maps.
• Table: use when exact values, sorting/filtering, or row-level inspection matters more than visual pattern.

Custom charts

Use custom chart callables when vizro.plotly.express wrappers do not cover the needed figure or the chart needs reusable parameters.

Keep custom chart functions:

• Pure and deterministic over input data/arguments.
• Returning a Plotly figure or Vizro-compatible figure object.
• Small enough to test independently.
• Free of server startup, file I/O, and network calls unless explicitly required.

Tables and grids

• Choose a table/grid when users need exact values, drill-down, sorting/filtering, or row selection.
• For action-linked graph/table behavior, route to core-components-data-actions after selecting the visual representation.
• Validate table model fields with scripts/inspect_vizro_schema.py --models Table AgGrid because table field names evolve.

Debug checklist

• Does the DataFrame contain each referenced column with the expected dtype?
• Does the chart render outside Vizro as a plain Plotly figure?
• Is the figure passed to vm.Graph(figure=...), not accidentally to a text/card/table field?
• Are color/facet/category orders explicit enough for the user's narrative?
• Are filters using the same data source/columns as the chart?
• If a chart is generated by an agent, validate/execute the code locally before embedding in a dashboard.

Evidence anchors

• vizro-core/src/vizro/plotly/express.py: wrapper API surface.
• vizro-core/src/vizro/figures/library.py: built-in figure helpers.
• vizro-core/src/vizro/models/types.py: figure typing.
• vizro-core/docs/pages/user-guides/custom-charts.md and table.md.
• vizro-core/examples/visual-vocabulary/README.md.
• vizro-e2e-flow/skills/selecting-vizro-charts/references/chart-best-practices.md.