Navigation & layoutBrick 0.1.2

Grid

Grid is Brick's two-dimensional layout primitive. `Grid.Root` creates exact equal columns or intrinsic responsive columns. Optional `Grid.Item` adds deliberate spans, line placement, and self-alignment; ordinary children remain valid grid items without wrappers.

Live example

Built from the published package

Interactive

Account

Billing

Security

Choose with confidence

Know when Grid is the right part

Use it when

Use Grid for peer-card collections, specimen matrices, comparison regions, settings summaries, exact equal tracks, intrinsic responsive collections, and asymmetric regions that need explicit item placement.

Choose another path when

Use Stack, HStack, or VStack for one-dimensional flow; Container for page width and gutters; Surface or Card for paint; and Atom DataGrid for interactive grid semantics and keyboard navigation. Grid is not a page-template language, breakpoint system, generic Box, or ARIA grid widget.

Installation and imports

tsx

import { Grid } from "@flowstack-ui/brick";
// or
import { Grid } from "@flowstack-ui/brick/grid";

import "@flowstack-ui/brick/styles.css";

The complete stylesheet above is the recommended default. For a measured route-aware build, replace it with the shared foundation and this component's stylesheet:

tsx

import "@flowstack-ui/brick/styles/core.css"; // once at the application root
import "@flowstack-ui/brick/styles/grid.css";

Add the modular stylesheet for every other Brick component the route renders. Do not combine modular styles with styles.css or tokens.css.

Public exports are Grid, GridRootProps, GridItemProps, GridRootElement, GridItemElement, GridColumns, GridLine, GridSpan, GridColumnSpan, GridGap, GridMinItemSize, GridAlign, GridJustify, GridSelfAlign, and GridSelfJustify.

Quick start

tsx

<Grid.Root minItemSize="md" gap="4">
  <Card.Root>Account</Card.Root>
  <Card.Root>Billing</Card.Root>
  <Card.Root>Security</Card.Root>
</Grid.Root>

Add Item only when placement is needed:

tsx

<Grid.Root columns={3} gap="4">
  <Card.Root>First</Card.Root>
  <Grid.Item columnSpan={2}>
    <Card.Root>Featured</Card.Root>
  </Grid.Item>
</Grid.Root>

Visual recipes and states

Explicit mode uses repeat(n, minmax(0, 1fr)). Intrinsic mode uses auto-fit with minimum sizes 8rem, 12rem, 16rem, 20rem, and 24rem for xs through xl. Gap values map to --brick-space-0 through --brick-space-6.

Numeric Item column placement is for explicit-column Roots. Intrinsic Roots use native auto-placement or columnSpan="full" because numeric placement can create unintended implicit columns as the responsive track count changes. Row placement may create native implicit rows.

Grid has no interactive, focus, disabled, loading, validation, appearance, paint, typography, or motion state.

Examples

Featured summary

tsx

<Grid.Root columns={4} gap="3">
  <Card.Root>Activity</Card.Root>
  <Grid.Item columnSpan={2}>
    <Card.Root>Featured report</Card.Root>
  </Grid.Item>
  <Card.Root>Storage</Card.Root>
  <Grid.Item columnSpan="full">
    <Card.Root>Workspace summary</Card.Root>
  </Grid.Item>
</Grid.Root>

Semantic list

tsx

<Grid.Root as="ul" minItemSize="sm" gap="3">
  <li>Design review</li>
  <li>Accessibility review</li>
  <li>Release review</li>
</Grid.Root>

Public contract

API

Start with the public parts and root options below. Components with multiple parts separate each area into its own named subsection.

Root

Prop	Values	Default
`as`	`div`, `span`, `section`, `article`, `nav`, `header`, `footer`, `main`, `aside`, `ul`, `ol`, `li`	`div`
`columns`	`1`–`12`	`1`
`minItemSize`	`xs`, `sm`, `md`, `lg`, `xl`	unset
`gap`	`0`, `1`, `2`, `3`, `4`, `5`, `6`	`0`
`rowGap`	`0`, `1`, `2`, `3`, `4`, `5`, `6`	inherits `gap`
`columnGap`	`0`, `1`, `2`, `3`, `4`, `5`, `6`	inherits `gap`
`align`	`stretch`, `start`, `center`, `end`, `baseline`	`stretch`
`justify`	`stretch`, `start`, `center`, `end`	`stretch`
`slot`	`string`	`grid`
`children`	`ReactNode`	optional

columns and minItemSize are mutually exclusive. Supplying minItemSize selects intrinsic mode; otherwise Root uses explicit mode.

Item

Prop	Values	Default
`as`	`div`, `span`, `section`, `article`, `header`, `footer`, `aside`, `li`	`div`
`columnSpan`	`1`–`12`, `full`	unset
`columnStart` / `columnEnd`	grid lines `1`–`13`	unset
`rowSpan`	`1`–`12`	unset
`rowStart` / `rowEnd`	grid lines `1`–`13`	unset
`align`	`auto`, `stretch`, `start`, `center`, `end`, `baseline`	`auto`
`justify`	`auto`, `stretch`, `start`, `center`, `end`	`auto`
`slot`	`string`	`grid-item`
`children`	`ReactNode`	optional

On each axis, a span and explicit end are mutually exclusive. A start may combine with a span or end. columnSpan="full" cannot combine with column start/end.

Shared responsibility

Accessibility

Grid adds no role, name, state, keyboard behavior, or focus target. Never add role="grid" merely because CSS Grid is used; interactive grid behavior belongs to Atom DataGrid.

DOM order remains reading and sequential focus order. Item placement never changes it. Dense flow, order, reverse behavior, and responsive visual reordering are deliberately excluded. Choose valid semantic hosts and children and name repeated landmarks.

Responsive behavior

Intrinsic mode responds to Grid's available inline size without JavaScript, viewport breakpoints, or responsive prop objects. Its min(100%, …) track safeguard prevents the minimum token from forcing page overflow.

Explicit mode keeps the requested track count. Application CSS owns a different mode or count at application breakpoints.

Stable visual contract

Styling and tokens

Customization

Use layout props first, then public variables or ordinary local CSS:

tsx

<Grid.Root
  columns={2}
  gap="2"
  style={{
    "--brick-grid-column-gap": "2rem",
    "--brick-grid-row-gap": "0.5rem",
    border: "2px dashed var(--brick-color-accent-border)",
    padding: "var(--brick-space-4)",
  }}
>
  <Card.Root>First</Card.Root>
  <Card.Root>Second</Card.Root>
</Grid.Root>

Paint and outer sizing remain consumer or Surface/Card responsibilities.

Tokens and CSS hooks

Stable Root hooks are .brick-grid, [data-slot="grid"], data-mode, data-columns, data-min-item-size, data-gap, data-row-gap, data-column-gap, data-align, and data-justify.

Stable Item hooks are .brick-grid-item, [data-slot="grid-item"], data-column-span, data-column-start, data-column-end, data-row-span, data-row-start, data-row-end, data-align, and data-justify.

Both parts expose the stable data-slot attribute.

Public variables:

--brick-grid-columns
--brick-grid-gap
--brick-grid-row-gap
--brick-grid-column-gap
--brick-grid-min-item-size
--brick-grid-item-column-start
--brick-grid-item-column-end
--brick-grid-item-row-start
--brick-grid-item-row-end

Advanced reference

Open these details only when you need to inspect DOM ownership, native forwarding, or lower-level composition.

Maintainer resources

Tests, playground evidence, source notes, and release history remain available without crowding the plug-and-play guide.

Source docs Changelog Playground