Grid
Responsive grid layout component that steps from one column up to six by the width of its own wrapper rather than the viewport, with shared gap sizes from xs to xl. The base for most editorial and card groups.
import { mergeProps } from "@base-ui/react/merge-props"
import { useRender } from "@base-ui/react/use-render"
import { cva, type VariantProps } from "class-variance-authority"
import { cn } from "cn"
const GRID_DEFAULTS = { cols: 3, gap: "lg" } as const
const containerGridVariants = cva("grid w-full grid-cols-1", {
variants: {
/**
* The most columns. Below 40rem of screen width the grid is one
* column (two for `6`); it steps up at 40rem and 48rem: `2` is two
* columns from 40rem, `3` two then three, `4` two then four, `5` three
* then five, and `6` three, then four, then six from 64rem. The default
* is 3.
*/
cols: {
1: "",
2: "sm:grid-cols-2",
3: "sm:grid-cols-2 md:grid-cols-3",
4: "sm:grid-cols-2 md:grid-cols-4",
5: "sm:grid-cols-3 md:grid-cols-5",
6: "grid-cols-2 sm:grid-cols-3 md:grid-cols-4 lg:grid-cols-6",
},
/**
* Space between items: `xs` 8px, `sm` 16px, `md` 24px, `lg` 40px, `xl` 64px, `px` 1px, `none` 0. `lg`
* is the default. The sizes are the `--gap-*` values in globals.css.
*/
gap: {
xs: "gap-(--gap-xs)",
sm: "gap-(--gap-sm)",
md: "gap-(--gap-md)",
lg: "gap-(--gap-lg)",
xl: "gap-(--gap-xl)",
px: "gap-px",
none: "gap-0",
},
},
defaultVariants: GRID_DEFAULTS,
})
type GridState = { slot: "grid" } & VariantProps<typeof containerGridVariants>
type GridProps = useRender.ComponentProps<"div", GridState> &
VariantProps<typeof containerGridVariants>
/**
* Columns follow the screen, stepping at 40rem and 48rem (and 64rem for six).
* Gap sizes read the shared `--gap-*` values in globals.css. The grid fills
* its parent's width: without that, a grid given `mx-auto` or set inside a
* centering parent shrinks to fit its content, and a part built on it that
* is a container collapses to nothing.
*
* className, render and every other prop go to the grid. To narrow a Grid, pass
* a `max-w-*` class or size its parent.
*/
function Grid({
className,
cols = GRID_DEFAULTS.cols,
gap = GRID_DEFAULTS.gap,
render,
...props
}: GridProps) {
const grid = useRender({
defaultTagName: "div",
render,
state: { slot: "grid", cols, gap },
props: mergeProps<"div">(
{ className: cn(containerGridVariants({ cols, gap }), className) },
props
),
})
return grid
}
export { Grid, type GridProps }
import { Grid } from "@/components/grid/grid"
// One tile per palette: its name and the two colors its swatch runs between.
const PALETTES = [
{ name: "Warmth", from: "oklch(0.75 0.13 80)", to: "oklch(0.55 0.15 40)" },
{ name: "Vesper", from: "oklch(0.55 0.12 300)", to: "oklch(0.25 0.06 280)" },
{ name: "Tide", from: "oklch(0.6 0.1 220)", to: "oklch(0.25 0.05 240)" },
{ name: "Fern", from: "oklch(0.62 0.08 150)", to: "oklch(0.2 0.02 150)" },
{ name: "Ember", from: "oklch(0.6 0.17 35)", to: "oklch(0.3 0.08 30)" },
{ name: "Graphite", from: "oklch(0.55 0 0)", to: "oklch(0.2 0 0)" },
] as const
/** A three-column Grid of palette tiles: one column on a phone, two from
* 40rem, three from 48rem. */
export default function GridDemo() {
return (
<Grid cols={3} gap="md" className="max-w-3xl">
{PALETTES.map((palette) => (
<div key={palette.name} className="flex flex-col gap-2">
<div
aria-hidden="true"
className="aspect-[4/3] rounded-lg"
style={{
background: `linear-gradient(${palette.from}, ${palette.to})`,
}}
/>
<span className="text-sm font-medium">{palette.name}</span>
</div>
))}
</Grid>
)
}
Installation
pnpm dlx shadcn@latest add @01orbital/gridnpx shadcn@latest add @01orbital/gridyarn dlx shadcn@latest add @01orbital/gridbunx --bun shadcn@latest add @01orbital/gridUsage
import { Grid } from "@/components/grid/grid"
// One tile per palette: its name and the two colors its swatch runs between.
const PALETTES = [
{ name: "Warmth", from: "oklch(0.75 0.13 80)", to: "oklch(0.55 0.15 40)" },
{ name: "Vesper", from: "oklch(0.55 0.12 300)", to: "oklch(0.25 0.06 280)" },
{ name: "Tide", from: "oklch(0.6 0.1 220)", to: "oklch(0.25 0.05 240)" },
{ name: "Fern", from: "oklch(0.62 0.08 150)", to: "oklch(0.2 0.02 150)" },
{ name: "Ember", from: "oklch(0.6 0.17 35)", to: "oklch(0.3 0.08 30)" },
{ name: "Graphite", from: "oklch(0.55 0 0)", to: "oklch(0.2 0 0)" },
] as const
/** A three-column Grid of palette tiles: one column on a phone, two from
* 40rem, three from 48rem. */
export default function GridDemo() {
return (
<Grid cols={3} gap="md" className="max-w-3xl">
{PALETTES.map((palette) => (
<div key={palette.name} className="flex flex-col gap-2">
<div
aria-hidden="true"
className="aspect-[4/3] rounded-lg"
style={{
background: `linear-gradient(${palette.from}, ${palette.to})`,
}}
/>
<span className="text-sm font-medium">{palette.name}</span>
</div>
))}
</Grid>
)
}This example installs with everything it uses:
pnpm dlx shadcn@latest add @01orbital/grid-demonpx shadcn@latest add @01orbital/grid-demoyarn dlx shadcn@latest add @01orbital/grid-demobunx --bun shadcn@latest add @01orbital/grid-demoAPI reference
Columns follow the screen, stepping at 40rem and 48rem (and 64rem for six). Gap sizes read the shared --gap-* values in globals.css. The grid fills its parent's width: without that, a grid given mx-auto or set inside a centering parent shrinks to fit its content, and a part built on it that is a container collapses to nothing.
className, render and every other prop go to the grid. To narrow a Grid, pass a max-w-* class or size its parent.
Prop
Type
It also accepts the props of the Base UI part it wraps, and the HTML attributes of the element it renders.
Dependencies
npm: @base-ui/react, class-variance-authority, cn. The CLI installs them for you.
Used in blocks
14 blocks are built with Grid; the first 12:
Accounts
Dark About with Team Roster
Dark Feature Grid with Eclipse
Dark Mission Control Team
Frosted Glass Guide Cards
Six-Person Team Grid
Tabbed Customer Story Grid
Team by Department
Team Centered Avatar Grid
Team Grid with Short Bios
Team Quote Cards
Team Roster with Open Roles
Last updated on