Vizro Chart Best Practices

Chart Selection

Never use: 3D charts, pie with 6+ slices, dual Y-axis, bar charts not starting at zero.

Plotly Conventions

• Plotly Express does not aggregate. Pre-aggregate in app.py or custom chart functions.
• Bar: sort by value (largest→smallest) unless time-based; always start at zero.
• Line: pre-aggregate and sort by x ascending.
• Remove axis title when ticks are self-explanatory. Remove legend title (keep items only).

Color Rules

• Plotly charts & KPI cards: Do not specify colors — no marker_color, hex codes, color_discrete_map, or color_discrete_sequence. This applies even for categories with apparent semantic meaning. Only override when the user explicitly asks.
• AG Grid: Does not pick up Vizro template colors automatically. Use from vizro.themes import palettes, colors for cell styling.
• See chart-best-practices.md for palette names and import patterns.

Custom Charts (@capture("graph"))

Use when: aggregation/sorting needed, update_layout()/update_traces() calls, reference lines, parameter-driven logic, dual-axis, multi-trace go.Figure(), shared legend control.

In practice, most bar and line charts need @capture("graph") functions that aggregate data inside. Inline px.bar(data_frame="raw", x="region", y="revenue") on detail-level data stacks individual rows as separate rectangles instead of summing — producing visually broken charts.

KPI Cards

• Use built-in kpi_card / kpi_card_reference from vizro.figures in Figure model.
• Never rebuild KPI cards as custom charts. Exception: strictly impossible with built-in (e.g. dynamic text).
• Titles go in figure args (_target_: kpi_card → title:), not on the component.

Tables

• Use vm.AgGrid with figure=dash_ag_grid(data_frame=...) from vizro.tables. AG Grid is the only table component you should write.
• Never use vm.Table / Dash DataTable. Never fake a table with Plotly (heatmap-with-text, px.imshow annotated as a table, scatter-with-text). Even small tables go in AG Grid; KPI cards or a horizontal bar chart are the only acceptable lighter alternatives.
• For custom column logic, write @capture("ag_grid") with data_frame as the exact DataFrame argument name (not df, not data).
• See the dashboard-build skill's example_ag_grid.py for the two canonical patterns (drop-in factory + @capture("ag_grid") for runtime-parameterized grids) and the Dash AG Grid / JS AG Grid knowledge-mapping notes.

Deep Dive

Load chart-best-practices.md when you need: extended chart type decision tree, Plotly Express formatting conventions (100% stacked bar, axis/legend cleanup), palette/color names and use cases, accessibility rules, or detailed @capture("graph") guidance.