Skip to content
Components

SimpleGrid

Equal-width column grid built on CSS Grid. cols and gap accept a single value or a per-breakpoint responsive object like { base: 1, md: 3 }; set responsiveMode to "container" to resolve breakpoints against the nearest container instead of the viewport.

01
02
03
04

Usage

import { SimpleGrid, SimpleGridProps } from "@instruments/materia-ui/components/simple-grid";

Best practices

  • SimpleGrid lays out equal-width columns - set cols (responsive, e.g. { base: 1, md: 3 }); when you need column spans or ordering, step up to Grid.

  • Set xGap/yGap for different column and row spacing; each overrides the gap shorthand on its own axis.

  • 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

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. 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).

colsLayoutResponsiveValue<number>3

Number of equal-width columns. Accepts a per-breakpoint responsive object.

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

Gap between items, from the spacing scale. Accepts a per-breakpoint responsive object.

responsiveModeResponsiveMode"screen"

Whether responsive values resolve against the viewport ("screen") or nearest container ("container").

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

Horizontal gap between columns. Accepts a per-breakpoint responsive object. Overrides gap on the inline axis.

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

Vertical gap between rows. Accepts a per-breakpoint responsive object. Overrides gap on the block axis.

refLayoutRef | undefined

Ref to the rendered host, whichever element as selects.

Also exports

  • interfaceSimpleGridProps