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)

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:

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.