Grid

A CSS grid container with columns, gap, and item spanning.

Usage#

import { Grid } from '@backstage/ui';

<Grid.Root columns="3" gap="4">
  <div>Item 1</div>
  <div>Item 2</div>
  <div>Item 3</div>
</Grid.Root>

API reference#

Grid.Root#

The grid container. Defines column count and gap between items.

Prop	Type	Default	Description
columns	123456789101112auto	auto	Number of columns. Use 1-12 for fixed layouts, auto to fit content.
gap	00.5auto	4	Space between items. Use higher values for separated layouts, lower for compact.
surface	0123dangerwarningsuccessauto	-	Surface level for theming. Use auto to increment from parent context.
children	ReactNode	-
className	string	-	Additional CSS class name for custom styling.
style	CSSProperties	-	Inline CSS styles object.
	00.5auto	-	Padding and margin properties for controlling spacing around the element.

Grid.Item#

A grid child with column and row spanning control.

Prop	Type	Default	Description
colSpan	123456789101112auto	-	Number of columns the item spans across.
colStart	123456789101112auto	-	Starting column position. Use with colEnd for explicit placement.
colEnd	123456789101112auto	-	Ending column position. Use with colStart for explicit placement.
rowSpan	123456789101112auto	-	Number of rows the item spans. Useful for tall content.
surface	0123dangerwarningsuccessauto	-	Surface level for theming. Use auto to increment from parent context.
children	ReactNode	-
className	string	-	Additional CSS class name for custom styling.
style	CSSProperties	-	Inline CSS styles object.

Examples#

Responsive columns#

Column count can change at different breakpoints.

<Grid.Root columns={{ initial: '2', md: '4' }} gap="4">
  <DecorativeBox>1</DecorativeBox>
  <DecorativeBox>2</DecorativeBox>
  <DecorativeBox>3</DecorativeBox>
  <DecorativeBox>4</DecorativeBox>
</Grid.Root>

Column spanning#

Use Grid.Item to span multiple columns.

Spans 2 columns

1 column

<Grid.Root columns="4" gap="4">
  <Grid.Item colSpan="2">
    <DecorativeBox>Spans 2 columns</DecorativeBox>
  </Grid.Item>
  <DecorativeBox>1 column</DecorativeBox>
  <DecorativeBox>1 column</DecorativeBox>
</Grid.Root>

Theming#

Our theming system is based on a mix between CSS classes, CSS variables and data attributes. If you want to customise this component, you can use one of these class names below.

bui-Grid
bui-Grid[data-bg="neutral-1"]
bui-Grid[data-bg="neutral-2"]
bui-Grid[data-bg="neutral-3"]
bui-Grid[data-bg="danger"]
bui-Grid[data-bg="warning"]
bui-Grid[data-bg="success"]