designing-vizro-layouts

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.