Writing Vizro YAML
Developmentwriting-vizro-yamlWriting Vizro YAML is an Agent Skill for development published in the mckinsey/vizro repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
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.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/mckinsey/vizro/blob/HEAD/vizro-e2e-flow/skills/writing-vizro-yaml/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/writing-vizro-yaml, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Vizro YAML & Component Reference
Critical Mistakes to Avoid
Each mistake below is expanded with code examples and fixes in yaml-reference.md.
@capture("graph")receives a DataFrame — usedata_framedirectly; never re-lookup viadata_manager[data_frame](causes blank charts).data_manageris not subscriptable — pre-process on raw DataFrame, then register.- Custom
_target_needs module prefix —_target_: custom_charts.my_chart, not_target_: my_chart. type: figurehas notitlefield — KPI titles go in_target_: kpi_cardargs.type: ag_gridrequires_target_: dash_ag_grid.- Parameter targets — format:
"component_id.argument_name", not"component_id.figure". - Quote YAML special chars in column names —
column: "Version #"(unquoted#starts a comment). - Filter
targets:— omit when you want to apply it to all components on the page whose data source includes defined filtercolumn. - Grid must be rectangular — same component index must span same columns in every row.
- 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:
| 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 |