Skip to content
Browse documentation
whisk/ui

Grid

Create responsive two-dimensional layouts.

Overview

Grid lays out related content in rows and columns using static, responsive track definitions and a shared gap.

Compare the layout primitives in the Choose a layout component table.

Use when

Content needs a two-dimensional, responsive layout.

Use instead

Use Stack or Flex for a simple single-axis arrangement.

Usage

Primary panel

Supporting panel

import { Box, Grid, Text } from "@smoothie-framework/whisk-react";

<Grid columns={{ base: 1, md: 2 }} gap={4}>
  <Box background="surface1" padding={4}>
    <Text>Primary panel</Text>
  </Box>
  <Box background="surface1" padding={4}>
    <Text>Supporting panel</Text>
  </Box>
</Grid>

Examples

Responsive columns

Start with a responsive track count when every item has the same importance. Grid places each child in source order.

Overview

Activity

Members

import { Box, Grid, Text } from "@smoothie-framework/whisk-react";

<Grid columns={{ base: 1, md: 3 }} gap={3}>
  <Box background="surface1" padding={3} rounded="md"><Text>Overview</Text></Box>
  <Box background="surface1" padding={3} rounded="md"><Text>Activity</Text></Box>
  <Box background="surface1" padding={3} rounded="md"><Text>Members</Text></Box>
</Grid>

Auto-fill

Use a static auto-fill template when cards should add columns as soon as there is room. With packaged styles.css, declare this literal template in utilityUses; the Vite or Rspack plugin scans literal templates automatically.

Overview

Activity

Members

import { Box, Grid, Text } from "@smoothie-framework/whisk-react";

<Grid columns="repeat(auto-fill, minmax(16rem, 1fr))" gap={3}>
  <Box padding={4} background="surface1" rounded="md"><Text>Overview</Text></Box>
  <Box padding={4} background="surface2" rounded="md"><Text>Activity</Text></Box>
  <Box padding={4} background="surface1" rounded="md"><Text>Members</Text></Box>
</Grid>

Tracks

Use a static template string when one column needs more room. Template strings must be literal values; values computed at runtime are not compiled. With packaged styles.css, declare this template in utilityUses; the Vite or Rspack plugin scans literal templates automatically.

Main content

Details

import { Box, Grid, Text } from "@smoothie-framework/whisk-react";

<Grid columns="2fr 1fr" gap={3}>
  <Box background="surface2" padding={4} rounded="md"><Text>Main content</Text></Box>
  <Box background="surface1" padding={4} rounded="md"><Text>Details</Text></Box>
</Grid>

Areas

Name template areas when the structure matters more than automatic placement. Keep source order meaningful, then stack the regions on narrow viewports.

Workspace

Main content

import { Grid, GridItem, Heading, Text } from "@smoothie-framework/whisk-react";

<Grid columns={{ base: 1, md: "12rem 1fr" }} rows={{ base: "auto auto auto", md: "auto 1fr" }} areas={{ base: '"header" "main" "sidebar"', md: '"header header" "sidebar main"' }} gap={3}>
  <GridItem as="header" area="header" padding={3} background="surface2"><Heading level={4} size="sm">Workspace</Heading></GridItem>
  <GridItem as="main" area="main" padding={3} background="surface1"><Text>Main content</Text></GridItem>
  <GridItem as="aside" area="sidebar" padding={3} background="surface1"><Text>Sidebar</Text></GridItem>
</Grid>

Span

Use GridItem when one child must span tracks. Leave ordinary children unwrapped when automatic placement is enough.

Overview

Activity

Full-width result

import { Grid, GridItem, Text } from "@smoothie-framework/whisk-react";

<Grid columns={{ base: 1, md: 4 }} gap={3}>
  <GridItem colSpan={{ base: 1, md: 2 }} background="surface2" padding={4} rounded="md"><Text>Overview</Text></GridItem>
  <GridItem colSpan={{ base: 1, md: 2 }} background="surface1" padding={4} rounded="md"><Text>Activity</Text></GridItem>
  <GridItem colSpan={{ base: 1, md: 4 }} background="surface3" padding={4} rounded="md"><Text>Full-width result</Text></GridItem>
</Grid>

Lists

Grid provides layout only. Choose a semantic host and list-item children when the content is a list.

  • Design review

  • Release notes

import { Grid, GridItem, Text } from "@smoothie-framework/whisk-react";

<Grid as="ul" columns={{ base: 1, md: 2 }} gap={3}>
  <GridItem as="li" background="surface1" padding={3} rounded="md"><Text>Design review</Text></GridItem>
  <GridItem as="li" background="surface1" padding={3} rounded="md"><Text>Release notes</Text></GridItem>
</Grid>

Props

Component props

PropTypeDefaultDescription
columnsResponsive<UtilityValue>noneSet a positive track count or a static template string at each breakpoint.
rowsResponsive<UtilityValue>noneSet a positive track count or a static row template at each breakpoint.
areas / areaResponsive<UtilityValue>noneDefine named regions on Grid with areas, then place a child with area. See Style props.
gapResponsive<SpacingStep>4Set the space between both rows and columns from the spacing scale.
inlinebooleanfalseRender an inline grid instead of a block-level grid.

Shared props

PropSupportedNotes
as / asChildYesChoose the rendered host with as, or merge the component props into one child with asChild.
Style propsYesUse the shared static style-prop surface. See Style props.
className / styleYesApplied to the rendered host.
refYesForwards to the rendered host.
Native HTML attributesYesNative attributes are forwarded to the rendered host.

Accessibility

Grid is a layout div, not an ARIA grid. Keep the DOM order meaningful as responsive tracks change, and use semantic children such as list items, articles, or controls. Use Table for tabular data and an ARIA grid only when you implement its keyboard behavior.