Grid

Usage

Overview

Grid arranges content in rows and columns with consistent gutters—ideal for card dashboards, form columns, and responsive feature grids. Prefer it when alignment must hold in two axes simultaneously; prefer FlexBox when layout is primarily one-dimensional.

When to use

Card grids (metrics, module launchers) that reflow across breakpoints.
Form layouts that specify column spans per field group.
Responsive patterns inside resizable panes when useContainerQueries keeps columns tied to the pane, not only the viewport.

When not to use

Simple stacked sections—FlexBox with gap is easier to reason about.
Full application shells with side navigation—follow existing shell primitives.
Single-row toolbars—FlexBox or Toolbar patterns fit better.

Variants

Column templates, minmax tracks, and gap should come from design tokens and shared constants—avoid one-off magic numbers in product code. For card galleries that should add columns as the container grows, use template={GridTemplate.AutoFillMinItem} (--layout-grid-auto-fill-min, 216px at a 16px root).

Anatomy

Grid container, track definitions, cells as direct children or nested regions. Container query hooks enable pane-aware breakpoints.

Content guidelines

Order cells in DOM reading order; avoid visually reordering in ways that harm keyboard and screen reader flow unless aria order is corrected.

Behavior and states

Loading grids should use skeleton cards sized to final layout to reduce CLS.
Empty grids should use Empty state spanning appropriate column width.

Best practices

Do prefer gap over per-cell margins—cleaner and more themeable.
Do enable useContainerQueries when grids live inside chat dividers, drawers, or resizable analytics panes (common in dispatch).
Don’t cram so many columns that touch targets and text truncate on real hardware.
Don’t mix unrelated densities in one grid without visual grouping.

Accessibility

Ensure focus order follows a sensible path (often row-major).
Maintain minimum spacing for text zoom; test 200% zoom in grid-heavy dashboards.

Box and layout primitives.
Card-style patterns often pair with grids.
Crud page for page-level structure around grid content.

Error Boundary / Accessibility

Grid / API and Development

On this page

Grid

Usage

Overview

When to use

Card grids (metrics, module launchers) that reflow across breakpoints.
Form layouts that specify column spans per field group.
Responsive patterns inside resizable panes when useContainerQueries keeps columns tied to the pane, not only the viewport.

When not to use

Simple stacked sections—FlexBox with gap is easier to reason about.
Full application shells with side navigation—follow existing shell primitives.
Single-row toolbars—FlexBox or Toolbar patterns fit better.

Variants

Anatomy

Grid container, track definitions, cells as direct children or nested regions. Container query hooks enable pane-aware breakpoints.

Content guidelines

Order cells in DOM reading order; avoid visually reordering in ways that harm keyboard and screen reader flow unless aria order is corrected.

Behavior and states

Loading grids should use skeleton cards sized to final layout to reduce CLS.
Empty grids should use Empty state spanning appropriate column width.

Best practices

Do prefer gap over per-cell margins—cleaner and more themeable.
Do enable useContainerQueries when grids live inside chat dividers, drawers, or resizable analytics panes (common in dispatch).
Don’t cram so many columns that touch targets and text truncate on real hardware.
Don’t mix unrelated densities in one grid without visual grouping.

Accessibility

Ensure focus order follows a sensible path (often row-major).
Maintain minimum spacing for text zoom; test 200% zoom in grid-heavy dashboards.

Box and layout primitives.
Card-style patterns often pair with grids.
Crud page for page-level structure around grid content.

Error Boundary / Accessibility

Grid / API and Development

On this page