Skip to main content

Grid

Grid places content in rows and columns, like a card gallery or a page with a sidebar. It supports responsive columns, spanning items, and named areas.

Import

import { Grid } from '@vortexlabs/vortex';
import type { GridProps } from '@vortexlabs/vortex';

Display

<Grid display="grid" columns={3} gap={3}>{children}</Grid>

Other links

Storybook
One
Two
Three
Four
Five
Six
<Grid
  display="grid"
  columns={3}
  gap={3}
>
  <Placeholder>One</Placeholder>
<Placeholder>Two</Placeholder>
<Placeholder>Three</Placeholder>
<Placeholder>Four</Placeholder>
<Placeholder>Five</Placeholder>
<Placeholder>Six</Placeholder>
</Grid>

Features

  • Supports grid, inline grid, and flex column display.
  • Creates responsive columns and gaps.
  • Spans items or places them in named areas.
  • Packs extra rows automatically.
  • Aligns content within cells.
  • Renders different HTML elements with as.
Reference Links
CSS-Tricks grid guide

Display

display is required: grid for a block-level grid, inline-grid for an inline one. On mobile, flex-column stacks children in source order and ignores item placement, so you don't need to reset each Grid.Item. Use a breakpoint object to switch back to grid on larger screens.

One
Two
Three
import { Grid, Placeholder } from "@vortexlabs/vortex";

<Grid display={{ xs: "flex-column", md: "grid" }} columns={3} gap={3}>
  <Placeholder>One</Placeholder>
  <Placeholder>Two</Placeholder>
  <Placeholder>Three</Placeholder>
</Grid>

Columns

Pass a number to columns for equal-width columns. Children fill the cells in order.

One
Two
Three
<Grid display="grid" columns={3} gap={3}>
  <Placeholder>One</Placeholder>
  <Placeholder>Two</Placeholder>
  <Placeholder>Three</Placeholder>
</Grid>

Responsive Columns

Pass a breakpoint object to change the column count by screen size.

Overview
Activity
Members
<Grid display="grid" columns={{ xs: 1, sm: 2, lg: 3 }} gap={{ xs: 3, md: 5 }}>
  <Placeholder>Overview</Placeholder>
  <Placeholder>Activity</Placeholder>
  <Placeholder>Members</Placeholder>
</Grid>

Custom Tracks

Pass a CSS string to columns for unequal widths.

Sidebar
Main content
<Grid display="grid" columns={{ xs: "1fr", sm: "10rem 1fr" }} gap={4}>
  <Placeholder height={24}>Sidebar</Placeholder>
  <Placeholder height={24}>Main content</Placeholder>
</Grid>

Row and Column Gaps

Use rowGap and columnGap when each axis needs different spacing. They override gap and use theme spacing units.

One
Two
Three
Four
<Grid display="grid" columns={2} columnGap={6} rowGap={2}>
  <Placeholder>One</Placeholder>
  <Placeholder>Two</Placeholder>
  <Placeholder>Three</Placeholder>
  <Placeholder>Four</Placeholder>
</Grid>

Spanning Items

Wrap content in Grid.Item and set columns or rows with CSS grid-line syntax to span several cells.

Full-width header
Main content
Aside
Footer
<Grid display="grid" columns={3} gap={3}>
  <Grid.Item columns="1 / -1">
    <Placeholder>Full-width header</Placeholder>
  </Grid.Item>
  <Grid.Item columns="span 2">
    <Placeholder height={24}>Main content</Placeholder>
  </Grid.Item>
  <Grid.Item rows="span 2">
    <Placeholder height="100%">Aside</Placeholder>
  </Grid.Item>
  <Grid.Item columns="span 2">
    <Placeholder>Footer</Placeholder>
  </Grid.Item>
</Grid>

Auto Placement

autoRows sets the height of rows created as items fill the grid. Set autoFlow="row-dense" to fill gaps left by spanning items with later ones.

One
Two
Three
Four
<Grid display="grid" columns={3} autoRows={20} autoFlow="row-dense" gap={3}>
  <Grid.Item columns="span 2">
    <Placeholder height="100%">One</Placeholder>
  </Grid.Item>
  <Grid.Item columns="span 2">
    <Placeholder height="100%">Two</Placeholder>
  </Grid.Item>
  <Placeholder height="100%">Three</Placeholder>
  <Placeholder height="100%">Four</Placeholder>
</Grid>

Named Areas

Name areas with gridTemplateAreas on the grid, then place each item with a matching gridArea.

Header
Sidebar
Main
<Grid
  display="grid"
  columns={{ xs: 1, sm: "1fr 2fr" }}
  gridTemplateAreas={{
    xs: '"header" "sidebar" "main"',
    sm: '"header header" "sidebar main"',
  }}
  gap={3}
>
  <Grid.Item gridArea="header">
    <Placeholder>Header</Placeholder>
  </Grid.Item>
  <Grid.Item gridArea="sidebar">
    <Placeholder height={24}>Sidebar</Placeholder>
  </Grid.Item>
  <Grid.Item gridArea="main">
    <Placeholder height={24}>Main</Placeholder>
  </Grid.Item>
</Grid>

Alignment

alignItems and justifyItems position content inside its cells. A Grid.Item can override them with alignSelf and justifySelf.

Start
Center
End
<Grid
  display="grid"
  columns={3}
  height="10rem"
  alignItems="center"
  justifyItems="center"
  padding={3}
  backgroundColor="surface-subtlest"
>
  <Grid.Item alignSelf="start">
    <Placeholder width={16}>Start</Placeholder>
  </Grid.Item>
  <Placeholder width={16}>Center</Placeholder>
  <Grid.Item alignSelf="end">
    <Placeholder width={16}>End</Placeholder>
  </Grid.Item>
</Grid>

Semantic Elements

Use as to render a semantic element and attributes for its native attributes. For a list, render each child as a Grid.Item with as="li".

  • Website
  • Mobile app
  • Design system
<Grid
  as="ul"
  display="grid"
  columns={{ xs: 1, sm: 3 }}
  gap={4}
  attributes={{ "aria-label": "Projects" }}
>
  <Grid.Item as="li">
    <Text>Website</Text>
  </Grid.Item>
  <Grid.Item as="li">
    <Text>Mobile app</Text>
  </Grid.Item>
  <Grid.Item as="li">
    <Text>Design system</Text>
  </Grid.Item>
</Grid>

Accessibility

Description
Grid adds no role or keyboard behavior; choose a semantic element with as when the content is a list or region.
Placement props, named areas, and dense autoFlow change visual position only; reading and keyboard order follow the source.