| name | designing-vizro-layouts |
| description | Use this skill when designing or building Vizro dashboard layouts — grid configuration, component sizing, filter/parameter placement, selector types, or container patterns. Activate when the user is creating wireframes, defining page structure, placing controls, or sizing charts. |
Vizro Layout Guidelines
Core Rules
- Use
type: grid (not vm.Layout). Recommended: 12 columns, row_min_height: "140px".
- Use
-1 for empty cells. Every component must form a perfect rectangle in the grid.
- Place 2–3 charts per row. Full-width only for time-series line charts.
- Modifying existing layouts: Replicate the original structure and apply only the technical constraints below. See layout-guidelines.md for details.
Component Sizing (12-col grid, 140px rows)
| Component | Columns | Rows | Height |
|---|
| KPI Card | 2–3 | 1 | 140px |
| Small Chart | 4 | 3 | 420px |
| Large Chart | 6 | 4–5 | 560–700px |
| Table | 12 | 4–6 | 560–840px |
KPI cards: Place in the page Grid with equal columns and equal rows per card (e.g. 4 cards = 3 cols each). Use -1 for remaining empty cells. See layout-guidelines.md for the full KPI count lookup table and YAML examples. Charts need at least 2–3 rows to avoid looking squeezed.
Filter Placement
- Page-level (left sidebar): filters shared across multiple components
- Container-level (above container): filters scoped only to the components inside that container
- Prefer Filters over Parameters. Do not set
targets: by default — all components containing the specified column are automatically affected. Only set targets: when you want to limit which components are affected.
Selectors
Default: Just provide the column name to Filter or Parameter — Vizro auto-selects the appropriate selector based on the data type. Only override when the auto-selected selector doesn't fit:
| Data type | Selector | Example |
|---|
| 2–4 options | RadioItems | Region (N/S/E/W) |
| 5+ options | Dropdown | Category (many) |
| Numeric range | RangeSlider | Price ($0–$1000) |
| Single number | Slider | Year (2020–2025) |
| Date | DatePicker | Order date |
| Multi-select | Checklist | Status (Active, etc.) |
Deep Dive
Load layout-guidelines.md when you need: grid YAML examples (correct vs incorrect), flexible width distributions, container patterns (plain/filled/outlined), visual hierarchy principles, or Vizro platform constraints.
