/designing-vizro-layouts

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](references/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](references/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](references/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.