Vizro YAML & Component Reference

Critical Mistakes to Avoid

Each mistake below is expanded with code examples and fixes in yaml-reference.md.

1. @capture("graph")

   receives a DataFrame — use

   data_frame

   directly; never re-lookup via

   data_manager[data_frame]

   (causes blank charts).

2. data_manager

   is not subscriptable — pre-process on raw DataFrame, then register.
3. Custom

   _target_

   needs module prefix —

   _target_: custom_charts.my_chart

   , not

   _target_: my_chart

   .

4. type: figure

   has no

   title

   field — KPI titles go in

   _target_: kpi_card

   args.

5. type: ag_grid

   requires

   _target_: dash_ag_grid

   .
6. Parameter targets — format:

   "component_id.argument_name"

   , not

   "component_id.figure"

   .
7. Quote YAML special chars in column names —

   column: "Version #"

   (unquoted

   #

   starts a comment).
8. Filter

   targets:

   — omit when you want to apply it to all components on the page whose data source includes defined filter

   column

   .
9. Grid must be rectangular — same component index must span same columns in every row.
10. Column type consistency — filter column must have same dtype across all targeted datasets.

Quick Patterns

# Standard chart (scatter — no aggregation needed, each row is one point)
- figure:
    _target_: scatter
    data_frame: sales_data
    x: units
    y: revenue
  type: graph
  title: Revenue vs Units

# KPI card (title inside figure args, NOT on component)
- figure:
    _target_: kpi_card
    data_frame: kpi_data
    value_column: Revenue
    title: Total Revenue
    value_format: "${value:,.0f}"
  type: figure

# AG Grid table
- figure:
    _target_: dash_ag_grid
    data_frame: sales_data
  type: ag_grid
  title: Sales Data

# Filter with targets
controls:
  - column: region
    targets: [chart_1, chart_2]
    type: filter

Key Imports

import vizro.models as vm
from vizro import Vizro
import vizro.plotly.express as px
from vizro.tables import dash_ag_grid
from vizro.figures import kpi_card, kpi_card_reference
from vizro.models.types import capture
from vizro.managers import data_manager
from vizro.themes import palettes, colors

Deep Dive

Load yaml-reference.md when you need expanded guidance. Key sections to search for:

## End-to-End Data Flow

## Data Registration

## Custom Charts

## AG Grid Tables

## Containers

## Tabs

## Critical Mistakes