Skip to content
Browse documentation
whisk/ui

GridItem

Place and span an item inside Grid.

Overview

GridItem is an optional Grid child wrapper for spanning tracks, applying static placement, and adding utility props.

Use when

A direct Grid child needs to span tracks, start at a static line, or receive its own utility styling.

Use instead

Use an ordinary semantic Grid child when automatic placement is enough, or Grid to define the tracks.

Usage

Main content

Sidebar

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

<Grid columns={{ base: 1, md: 3 }} gap={3}>
  <GridItem colSpan={{ base: 1, md: 2 }} background="surface2" padding={3}>
    <Text>Main content</Text>
  </GridItem>
  <Text>Sidebar</Text>
</Grid>

Examples

Responsive column span

Use a responsive span when a primary panel should take more tracks on a wider layout. GridItem remains one column wide at the base breakpoint.

Primary workspace

Activity

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

<Grid columns={{ base: 1, md: 4 }} gap={3}>
  <GridItem colSpan={{ base: 1, md: 3 }} background="surface2" padding={4} rounded="md">
    <Text>Primary workspace</Text>
  </GridItem>
  <GridItem background="surface1" padding={4} rounded="md">
    <Text>Activity</Text>
  </GridItem>
</Grid>

Row span

Use rowSpan for a panel that should occupy more than one row. Give the parent enough items and defined tracks for the placement to be visible.

Summary

Activity

Members

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

<Grid columns={3} rows={2} gap={3}>
  <GridItem rowSpan={2} background="surface2" padding={4} rounded="md"><Text>Summary</Text></GridItem>
  <GridItem background="surface1" padding={4} rounded="md"><Text>Activity</Text></GridItem>
  <GridItem background="surface1" padding={4} rounded="md"><Text>Members</Text></GridItem>
</Grid>

Start line

Use an explicit start line sparingly. Source order and automatic placement are easier to maintain when they already express the intended layout.

Scheduled report

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

<Grid columns={3} gap={3}>
  <GridItem colStart={2} colSpan={2} background="surface2" padding={4} rounded="md">
    <Text>Scheduled report</Text>
  </GridItem>
</Grid>

Semantic child

Use as or asChild when GridItem represents a meaningful element. Placement changes the layout, not the element's semantics.

Release notes

Read the latest changes.

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

<Grid columns={{ base: 1, md: 2 }} gap={3}>
  <GridItem as="article" background="surface1" padding={4} rounded="md">
    <Stack gap={1}>
      <Heading level={4} size="sm">Release notes</Heading>
      <Text color="subtle">Read the latest changes.</Text>
    </Stack>
  </GridItem>
</Grid>

Props

Component props

PropTypeDefaultDescription
colSpanResponsive<UtilityValue>noneSpan a static number of column tracks. Numeric values must be positive safe integers.
rowSpanResponsive<UtilityValue>noneSpan a static number of row tracks. Numeric values must be positive safe integers.
colStart | colEnd | rowStart | rowEndResponsive<UtilityValue>nonePlace the item at a static grid line when automatic placement is not enough.
areaResponsive<UtilityValue>nonePlace the item in a named area defined by the parent 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

GridItem renders a div by default and does not create an ARIA gridcell, list item, or landmark. Use as or asChild to preserve the right HTML semantics. Keep source order meaningful: visual placement must not make the reading or keyboard order confusing.