Usage
Grid defines column (and optional row) tracks with design tokens—ideal for dashboards, queue boards, and sidebar + main shells. Prefer it when alignment must hold in two axes or when track ratios are structural (2:1, fixed metric column + flexible peers). Prefer FlexBox with item={FlexItem.*} for one-dimensional flex rows and scroll hosts inside a pane.
GridTemplate.EqualThirds, TwoOne, ThreeOne, EqualTenths).QueueMetricsStandard, QueueMetricsEct).SidebarStartMain, MainSidebarEnd) with collapseBelow inside a container query host.AutoFillMinItem).areas with GRID_AREA_PRESETS or defineGridAreas; see API and Development).columnSpan={{ initial, md, … }}; see API and Development).subgrid with columnSpan / rowSpan; see API and Development).FlexBox and item={FlexItem.*} are easier.FlexItem.FillScroll on Box / FlexBox, not grid tracks.grid-template-columns in consumer CSS—request or use an existing GridTemplate.display: contents wrappers to fake alignment between nested groups—use subgrid on the nested Grid.Box / FlexBox props. Put paint on Box inside Grid / GridItem. For a cell that should grow and scroll, wrap content in FlexBox item={FlexItem.FillScroll} with a definite height on the grid row or cell host—not className flex rules.
| Layout need | Prefer |
|---|---|
| 2:1 or 3:1 columns | Grid template={GridTemplate.TwoOne} or ThreeOne |
| Ten equal columns | Grid template={GridTemplate.EqualTenths} |
| Queue metrics (231px / 337px leading track) | QueueMetricsStandard / QueueMetricsEct |
| One row, one child eats leftover height + scrolls | FlexBox item={FlexItem.FillScroll} inside the cell |
| Toolbar + growing body in a column | Outer FlexBox; toolbar item={FlexItem.Fixed}, body FillScroll |
Grid subgrid={GridSubgrid.Columns} and columnSpan={GridSpan.Full} and its children sit on the parent's column tracks, so labels in separate sections share one column. GridSubgrid.Rows with rowSpan does the same for rows, so card parts line up across a row of cards. The span goes on the subgrid itself, never on a wrapping GridItem or Box. Leave gap unset to keep the parent's gutters.
Grid container, optional GridItem for span, Box children for content and paint. Enable containerType={ContainerType.InlineSize} on an ancestor when using collapseBelow.
gap from GridGap tokens.collapseBelow with container queries when grids live in resizable panes.background, border, or style on Grid / GridItem—use Box inside cells.flex and basis when a GridTemplate exists.template, rows or collapseBelow on an axis a subgrid adopts; the parent owns those tracks.flow={GridFlow.RowDense} when focus path matters.FlexItem, alignSelf, and paint inside cells.