XDS — Design System

Grid@xds/core · XDSGrid v0.0.13

Usage

A CSS grid layout container for arranging children in rows and columns. Use Grid for card galleries, dashboards, and any multi-column layout. Supports fixed column counts and responsive columns that reflow based on available width.

ts
import {XDSGrid} from '@xds/core/Grid'

Best practices

Guidance	Practices
Do	Use responsive columns for layouts that should adapt to screen size — `columns={{minWidth: 280}}`.
Do	Cap the column count with `max` to prevent rows from getting too wide on large screens.
Do	Use `repeat: 'fill'` (the default) for consistent item widths. Use `'fit'` when items should stretch to fill leftover space.
Don't	Write manual CSS grid — Grid handles spacing and responsive behavior for you.
Don't	Use `XDSHStack` with wrapping for grids — use Grid instead.

Sub-components

Grid is a compound component with 2 sub-components.

XDSGrid

Grid container with fixed or responsive columns.

Prop	Type	Description
columns	number \| {minWidth: number, max?: number, repeat?: 'fill' \| 'fit'}	Column configuration. Use a number for fixed columns (e.g. `columns={3}`). Use an object for responsive columns: `minWidth` sets the minimum column width in px, `repeat` controls track behavior (`"fill"` preserves empty tracks for consistent widths, `"fit"` collapses empty tracks so items stretch; defaults to `"fill"`), and `max` caps the maximum number of columns.
minChildWidth	number	Deprecated — use `columns={{minWidth: 280}}` instead. Minimum item width in px; enables responsive auto-fit.
width	number \| string	Container width.
height	number \| string	Container height.
gap	SpacingStep	Spacing between all items.
rowGap	SpacingStep	Row spacing; overrides `gap` for the row axis.
columnGap	SpacingStep	Column spacing; overrides `gap` for the column axis.
align	GridAlignment (default: 'stretch')	Vertical alignment of items.
justify	GridAlignment (default: 'stretch')	Horizontal alignment of items.
children	ReactNode	Grid content.
xstyle	StyleXStyles	StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}.

XDSGridSpan

Grid item that spans multiple columns or rows.

Prop	Type	Description
columns	number \| 'full'	Columns to span; use `'full'` to span the entire row.
rows	number	Rows to span.
children	ReactNode	Content.

Examples

Common configurations, variations, and states.

Grid — Card GalleryCard gallery with responsive columns that maintain consistent widths

tsx
'use client';
import {XDSGrid} from '@xds/core/Grid';
import {XDSCard} from '@xds/core/Card';
import {XDSVStack} from '@xds/core/Stack';
import {XDSText} from '@xds/core/Text';
const cards = [
  {title: 'Getting Started', description: 'Learn the basics of the platform.'},
  {title: 'Components', description: 'Browse the full component library.'},
  {title: 'Design Tokens', description: 'Colors, spacing, and typography.'},
  {title: 'Theming', description: 'Customize the look and feel.'},
  {title: 'Accessibility', description: 'Build inclusive experiences.'},
  {title: 'Patterns', description: 'Common UI composition patterns.'},
  {title: 'Migration Guide', description: 'Upgrading from previous versions.'},
  {title: 'API Reference', description: 'Detailed prop and hook docs.'},
];
export default function GridGalleryExample() {
  return (
    <XDSGrid columns={{minWidth: 280}} gap={5}>
      {cards.map(card => (
        <XDSCard key={card.title}>
          <XDSVStack gap={1}>
            <XDSText type="label" display="block">
              {card.title}
            </XDSText>
            <XDSText type="supporting" display="block">
              {card.description}
            </XDSText>
          </XDSVStack>
        </XDSCard>
      ))}
    </XDSGrid>
  );
}

Grid — Column SpanningGrid with featured items spanning two, three, and all columns

tsx
'use client';
import {XDSGrid, XDSGridSpan} from '@xds/core/Grid';
import {XDSCard} from '@xds/core/Card';
import {XDSVStack} from '@xds/core/Stack';
import {XDSText} from '@xds/core/Text';
export default function GridWithGridSpan() {
  return (
    <XDSGrid columns={4} gap={4}>
      <XDSGridSpan columns={2}>
        <XDSCard variant="cyan">
          <XDSVStack gap={1}>
            <XDSText type="label" display="block">
              Featured Release
            </XDSText>
            <XDSText type="supporting" display="block">
              XDS 4.0 is now available with new layout primitives
            </XDSText>
          </XDSVStack>
        </XDSCard>
      </XDSGridSpan>
      <XDSCard>
        <XDSText type="label" display="block">
          Components
        </XDSText>
        <XDSText type="supporting" display="block">
          54 available
        </XDSText>
      </XDSCard>
      <XDSCard>
        <XDSText type="label" display="block">
          Templates
        </XDSText>
        <XDSText type="supporting" display="block">
          28 available
        </XDSText>
      </XDSCard>
      <XDSCard>
        <XDSText type="label" display="block">
          Tokens
        </XDSText>
        <XDSText type="supporting" display="block">
          120 defined
        </XDSText>
      </XDSCard>
      <XDSGridSpan columns={3}>
        <XDSCard variant="cyan">
          <XDSVStack gap={1}>
            <XDSText type="label" display="block">
              Migration Guide
            </XDSText>
            <XDSText type="supporting" display="block">
              Step-by-step instructions for upgrading from v3 to v4
            </XDSText>
          </XDSVStack>
        </XDSCard>
      </XDSGridSpan>
      <XDSGridSpan columns="full">
        <XDSCard variant="cyan">
          <XDSVStack gap={1}>
            <XDSText type="label" display="block">
              Community Showcase
            </XDSText>
            <XDSText type="supporting" display="block">
              See how teams are building with XDS across the organization
            </XDSText>
          </XDSVStack>
        </XDSCard>
      </XDSGridSpan>
    </XDSGrid>
  );
}

Grid — Dashboard LayoutDashboard layout with mixed-size widgets and a full-width summary row

tsx
'use client';
import {XDSGrid, XDSGridSpan} from '@xds/core/Grid';
import {XDSCard} from '@xds/core/Card';
import {XDSText} from '@xds/core/Text';
const metrics = [
  {label: 'Revenue', value: '$48,290'},
  {label: 'Active Users', value: '12,841'},
  {label: 'Conversion', value: '3.2%'},
  {label: 'Avg Response', value: '245ms'},
];
export default function GridDashboardLayout() {
  return (
    <XDSGrid columns={4} gap={4}>
      <XDSGridSpan columns={2} rows={2}>
        <XDSCard>
          <XDSText type="label" display="block">
            Weekly Traffic
          </XDSText>
          <XDSText type="supporting" display="block">
            Page views and unique visitors over the last 7 days
          </XDSText>
        </XDSCard>
      </XDSGridSpan>
      {metrics.map(m => (
        <XDSCard key={m.label}>
          <XDSText type="supporting" display="block">
            {m.label}
          </XDSText>
          <XDSText type="label" display="block">
            {m.value}
          </XDSText>
        </XDSCard>
      ))}
      <XDSGridSpan columns="full">
        <XDSCard>
          <XDSText type="label" display="block">
            Recent Activity
          </XDSText>
          <XDSText type="supporting" display="block">
            Latest events across all projects
          </XDSText>
        </XDSCard>
      </XDSGridSpan>
    </XDSGrid>
  );
}

Grid — Responsive Auto-FitResponsive grid where cards stretch to fill remaining space

tsx
'use client';
import {XDSGrid} from '@xds/core/Grid';
import {XDSCard} from '@xds/core/Card';
import {XDSVStack} from '@xds/core/Stack';
import {XDSText} from '@xds/core/Text';
const teams = [
  {name: 'Design Systems', members: 8},
  {name: 'Frontend Platform', members: 12},
  {name: 'Developer Experience', members: 6},
  {name: 'Accessibility', members: 4},
  {name: 'Performance', members: 7},
  {name: 'Mobile Infrastructure', members: 9},
];
export default function GridResponsiveAutoFit() {
  return (
    <XDSGrid columns={{minWidth: 200, repeat: 'fit'}} gap={4}>
      {teams.map(team => (
        <XDSCard key={team.name}>
          <XDSVStack gap={1}>
            <XDSText type="label" display="block">
              {team.name}
            </XDSText>
            <XDSText type="supporting" display="block">
              {team.members} members
            </XDSText>
          </XDSVStack>
        </XDSCard>
      ))}
    </XDSGrid>
  );
}

Showcase source

tsx
'use client';
import {XDSGrid} from '@xds/core/Grid';
export default function GridShowcase() {
  return (
    <XDSGrid columns={3} gap={4}>
      {Array.from({length: 6}, (_, i) => (
        <div
          key={i}
          style={{
            padding: 16,
            backgroundColor: 'var(--color-background-body)',
            borderRadius: 'var(--radius-element, 8px)',
            textAlign: 'center',
          }}>
          Item {i + 1}
        </div>
      ))}
    </XDSGrid>
  );
}

Usage

import {XDSGrid} from '@xds/core/Grid'

Best practices

Guidance	Practices
Do	Use responsive columns for layouts that should adapt to screen size — `columns={{minWidth: 280}}`.
Do	Cap the column count with `max` to prevent rows from getting too wide on large screens.
Do	Use `repeat: 'fill'` (the default) for consistent item widths. Use `'fit'` when items should stretch to fill leftover space.
Don't	Write manual CSS grid — Grid handles spacing and responsive behavior for you.
Don't	Use `XDSHStack` with wrapping for grids — use Grid instead.

Prop

Type

Description

columns

number | {minWidth: number, max?: number, repeat?: 'fill' | 'fit'}

Column configuration. Use a number for fixed columns (e.g. `columns={3}`). Use an object for responsive columns: `minWidth` sets the minimum column width in px, `repeat` controls track behavior (`"fill"` preserves empty tracks for consistent widths, `"fit"` collapses empty tracks so items stretch; defaults to `"fill"`), and `max` caps the maximum number of columns.

minChildWidth

number

Deprecated — use `columns={{minWidth: 280}}` instead. Minimum item width in px; enables responsive auto-fit.

width

number | string

Container width.

height

number | string

Container height.

gap

SpacingStep

Spacing between all items.

rowGap

SpacingStep

Row spacing; overrides `gap` for the row axis.

columnGap

SpacingStep

Column spacing; overrides `gap` for the column axis.

align

GridAlignment (default: 'stretch')

Vertical alignment of items.

justify

GridAlignment (default: 'stretch')

Horizontal alignment of items.

children

ReactNode

Grid content.

xstyle

StyleXStyles

StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}.

Prop

Type

Description

columns

number | 'full'

Columns to span; use `'full'` to span the entire row.

rows

number

Rows to span.

children

ReactNode

Content.

tsx

'use client'; import {XDSGrid} from '@xds/core/Grid'; import {XDSCard} from '@xds/core/Card'; import {XDSVStack} from '@xds/core/Stack'; import {XDSText} from '@xds/core/Text'; const cards = [ {title: 'Getting Started', description: 'Learn the basics of the platform.'}, {title: 'Components', description: 'Browse the full component library.'}, {title: 'Design Tokens', description: 'Colors, spacing, and typography.'}, {title: 'Theming', description: 'Customize the look and feel.'}, {title: 'Accessibility', description: 'Build inclusive experiences.'}, {title: 'Patterns', description: 'Common UI composition patterns.'}, {title: 'Migration Guide', description: 'Upgrading from previous versions.'}, {title: 'API Reference', description: 'Detailed prop and hook docs.'}, ]; export default function GridGalleryExample() { return ( <XDSGrid columns={{minWidth: 280}} gap={5}> {cards.map(card => ( <XDSCard key={card.title}> <XDSVStack gap={1}> <XDSText type="label" display="block"> {card.title} </XDSText> <XDSText type="supporting" display="block"> {card.description} </XDSText> </XDSVStack> </XDSCard> ))} </XDSGrid> ); }

tsx

'use client'; import {XDSGrid, XDSGridSpan} from '@xds/core/Grid'; import {XDSCard} from '@xds/core/Card'; import {XDSVStack} from '@xds/core/Stack'; import {XDSText} from '@xds/core/Text'; export default function GridWithGridSpan() { return ( <XDSGrid columns={4} gap={4}> <XDSGridSpan columns={2}> <XDSCard variant="cyan"> <XDSVStack gap={1}> <XDSText type="label" display="block"> Featured Release </XDSText> <XDSText type="supporting" display="block"> XDS 4.0 is now available with new layout primitives </XDSText> </XDSVStack> </XDSCard> </XDSGridSpan> <XDSCard> <XDSText type="label" display="block"> Components </XDSText> <XDSText type="supporting" display="block"> 54 available </XDSText> </XDSCard> <XDSCard> <XDSText type="label" display="block"> Templates </XDSText> <XDSText type="supporting" display="block"> 28 available </XDSText> </XDSCard> <XDSCard> <XDSText type="label" display="block"> Tokens </XDSText> <XDSText type="supporting" display="block"> 120 defined </XDSText> </XDSCard> <XDSGridSpan columns={3}> <XDSCard variant="cyan"> <XDSVStack gap={1}> <XDSText type="label" display="block"> Migration Guide </XDSText> <XDSText type="supporting" display="block"> Step-by-step instructions for upgrading from v3 to v4 </XDSText> </XDSVStack> </XDSCard> </XDSGridSpan> <XDSGridSpan columns="full"> <XDSCard variant="cyan"> <XDSVStack gap={1}> <XDSText type="label" display="block"> Community Showcase </XDSText> <XDSText type="supporting" display="block"> See how teams are building with XDS across the organization </XDSText> </XDSVStack> </XDSCard> </XDSGridSpan> </XDSGrid> ); }

tsx

'use client'; import {XDSGrid, XDSGridSpan} from '@xds/core/Grid'; import {XDSCard} from '@xds/core/Card'; import {XDSText} from '@xds/core/Text'; const metrics = [ {label: 'Revenue', value: '$48,290'}, {label: 'Active Users', value: '12,841'}, {label: 'Conversion', value: '3.2%'}, {label: 'Avg Response', value: '245ms'}, ]; export default function GridDashboardLayout() { return ( <XDSGrid columns={4} gap={4}> <XDSGridSpan columns={2} rows={2}> <XDSCard> <XDSText type="label" display="block"> Weekly Traffic </XDSText> <XDSText type="supporting" display="block"> Page views and unique visitors over the last 7 days </XDSText> </XDSCard> </XDSGridSpan> {metrics.map(m => ( <XDSCard key={m.label}> <XDSText type="supporting" display="block"> {m.label} </XDSText> <XDSText type="label" display="block"> {m.value} </XDSText> </XDSCard> ))} <XDSGridSpan columns="full"> <XDSCard> <XDSText type="label" display="block"> Recent Activity </XDSText> <XDSText type="supporting" display="block"> Latest events across all projects </XDSText> </XDSCard> </XDSGridSpan> </XDSGrid> ); }

tsx

'use client'; import {XDSGrid} from '@xds/core/Grid'; import {XDSCard} from '@xds/core/Card'; import {XDSVStack} from '@xds/core/Stack'; import {XDSText} from '@xds/core/Text'; const teams = [ {name: 'Design Systems', members: 8}, {name: 'Frontend Platform', members: 12}, {name: 'Developer Experience', members: 6}, {name: 'Accessibility', members: 4}, {name: 'Performance', members: 7}, {name: 'Mobile Infrastructure', members: 9}, ]; export default function GridResponsiveAutoFit() { return ( <XDSGrid columns={{minWidth: 200, repeat: 'fit'}} gap={4}> {teams.map(team => ( <XDSCard key={team.name}> <XDSVStack gap={1}> <XDSText type="label" display="block"> {team.name} </XDSText> <XDSText type="supporting" display="block"> {team.members} members </XDSText> </XDSVStack> </XDSCard> ))} </XDSGrid> ); }

tsx

'use client'; import {XDSGrid} from '@xds/core/Grid'; export default function GridShowcase() { return ( <XDSGrid columns={3} gap={4}> {Array.from({length: 6}, (_, i) => ( <div key={i} style={{ padding: 16, backgroundColor: 'var(--color-background-body)', borderRadius: 'var(--radius-element, 8px)', textAlign: 'center', }}> Item {i + 1} </div> ))} </XDSGrid> ); }