/writing-vizro-yaml

name: writing-vizro-yaml
description: Use this skill when writing or debugging Vizro YAML dashboard configurations — component syntax, data_manager registration, custom function wiring, filter/parameter setup, or AG Grid tables. Activate when the user is building a Vizro app, encountering YAML or runtime errors, or asking about Vizro component patterns.

Vizro YAML & Component Reference

Critical Mistakes to Avoid

Each mistake below is expanded with code examples and fixes in [yaml-reference.md](references/yaml-reference.md).

1. **`@capture("graph")` receives a DataFrame** — use `data_frame` directly; never re-lookup via `data_manager[data_frame]` (causes blank charts). 1. **`data_manager` is not subscriptable** — pre-process on raw DataFrame, then register. 1. **Custom `_target_` needs module prefix** — `_target_: custom_charts.my_chart`, not `_target_: my_chart`. 1. **`type: figure` has no `title` field** — KPI titles go in `_target_: kpi_card` args. 1. **`type: ag_grid` requires `_target_: dash_ag_grid`**. 1. **Parameter targets** — format: `"component_id.argument_name"`, not `"component_id.figure"`. 1. **Quote YAML special chars in column names** — `column: "Version #"` (unquoted `#` starts a comment). 1. **Filter `targets:`** — omit when you want to apply it to all components on the page whose data source includes defined filter `column`. 1. **Grid must be rectangular** — same component index must span same columns in every row. 1. **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](references/yaml-reference.md) when you need expanded guidance. Key sections to search for:

| Need | Search for | | ------------------------------ | ---------------------------- | | App structure | `## End-to-End Data Flow` | | Data registration | `## Data Registration` | | Custom charts | `## Custom Charts` | | AG Grid (heatmap, inline bars) | `## AG Grid Tables` | | Containers / Tabs | `## Containers` or `## Tabs` | | Expanded mistake fixes | `## Critical Mistakes` |