Skip to content
Components

Grid

CSS Grid layout with configurable columns, gaps, and alignment; columns, the gaps and the alignment props accept a responsive object keyed by breakpoint. Compose column spans with GridCol children.

Red
Amber
Green
Teal
Blue
Violet

Usage

import { Grid, GridCol, GridColProps, GridProps } from "@instruments/materia-ui/components/grid";

Best practices

  • Grid gives full 2-D control - compose GridCol children with span/start/order; if you only need equal-width responsive columns, SimpleGrid is lighter.

  • columns, gap, and alignment each accept a per-breakpoint object; responsiveMode="container" resolves them against the nearest container query.

  • For a grid whose tracks come from its own className or its children (grid-cols-[...], grid-flow-col), pass columns="none": it emits no column classes and no default alignment. "none" is a whole value, not a breakpoint key. inline (a boolean) renders inline-grid.

  • as and render are mutually exclusive (render wins, dev-warned); as draws from the closed layout vocabulary, so as="button" is a type error (use Button).

  • Use as to change the element (a tag); use render only to swap in a component (e.g. a router Link). Never render={<Box as=…/>} - pass as directly.

Props

Grid

PropTypeDefaultDescription
alignLayoutResponsiveValue<FlexAlign>

Align items on the block axis. Can be responsive.

as"div" | "article" | "aside" | "figcaption" | "figure" | "footer" | "header" | "li" | "main" | "nav" | "ol" | "section" | "span" | "ul"

Render as a different host element from the closed layout vocabulary ({@link LayoutElement}). The set is deliberately closed: as="button" is a type error, because the design-system answer is the Button component. Event handlers and the ref accept any host element. as and render are mutually exclusive; if both are passed, render wins (a dev-only warning fires).

columns"none" | LayoutResponsiveValue<number>

Total columns in the layout. Can be a number or responsive object. Defaults to 12. "none" sets no column template: tracks are implicit (or come from className, such as grid-cols-[2fr_3fr] or grid-rows-[1fr]), and no default align/justify is emitted, so the grid behaves like a plain CSS grid whose implicit tracks stretch to fill it.

gapLayoutResponsiveValue<"base" | "none" | "2xs" | "xs" | "sm" | "lg" | "xl" | "2xl" | "3xl" | "3xs">

Gap between items. Can be responsive. Defaults to "base" (16px).

growboolean

When true, columns grow equally to fill available space.

inlinebooleanfalse

Render as inline-grid instead of grid.

justifyLayoutResponsiveValue<FlexJustify>

Justify items on the inline axis. Can be responsive.

responsiveModeResponsiveMode

Responsive mode: "screen" (viewport) or "container" (container queries).

xGapLayoutResponsiveValue<"base" | "none" | "2xs" | "xs" | "sm" | "lg" | "xl" | "2xl" | "3xl" | "3xs">

Horizontal gap between items. Can be responsive. Overrides gap on inline axis.

yGapLayoutResponsiveValue<"base" | "none" | "2xs" | "xs" | "sm" | "lg" | "xl" | "2xl" | "3xl" | "3xs">

Vertical gap between items. Can be responsive. Overrides gap on block axis.

refLayoutRef | undefined

Ref to the rendered host, whichever element as selects.

GridCol

PropTypeDefaultDescription
as"div" | "article" | "aside" | "figcaption" | "figure" | "footer" | "header" | "li" | "main" | "nav" | "ol" | "section" | "span" | "ul"

Render as a different host element from the closed layout vocabulary ({@link LayoutElement}). The set is deliberately closed: as="button" is a type error, because the design-system answer is the Button component. Ref and event-handler types remain the default element's (HTMLDivElement). as and render are mutually exclusive; if both are passed, render wins (a dev-only warning fires).

orderLayoutResponsiveValue<OrderValue>

CSS order value (1-12, "first", "last", "none"). Can be responsive.

responsiveModeResponsiveMode

Responsive mode: "screen" (viewport) or "container" (container queries).

spanLayoutResponsiveValue<number>

Number of columns this item spans. Can be responsive.

startLayoutResponsiveValue<number>

Column start position (1-based). Can be responsive.

Also exports

  • interfaceGridColProps
  • interfaceGridProps

Composition

Used by

Alert, Chart, CheckboxField, DataGrid, DeliveryBanner, DescriptionList, MegaMenu, MonthYearPicker, PixelLoader, PromptPanel, QuickView, RadioGroup, SearchInput, SiteFooter, StreamingText, ThinkingTrace