XDSGrid@xds/core · Grid

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.

Best practices

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

Import

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

Props

PropTypeDescription
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
numberDeprecated — use `columns={{minWidth: 280}}` instead. Minimum item width in px; enables responsive auto-fit.
width
number | stringContainer width.
height
number | stringContainer height.
gap
SpacingStepSpacing between all items.
rowGap
SpacingStepRow spacing; overrides `gap` for the row axis.
columnGap
SpacingStepColumn spacing; overrides `gap` for the column axis.
align
GridAlignment (default: 'stretch')Vertical alignment of items.
justify
GridAlignment (default: 'stretch')Horizontal alignment of items.
children
ReactNodeGrid content.
xstyle
StyleXStylesStyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value — not an inline style object like style={{}}.

Sub-components

Grid is a compound component with 2 sub-components.

XDSGrid

Grid container with fixed or responsive columns.
PropTypeDescription
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
numberDeprecated — use `columns={{minWidth: 280}}` instead. Minimum item width in px; enables responsive auto-fit.
width
number | stringContainer width.
height
number | stringContainer height.
gap
SpacingStepSpacing between all items.
rowGap
SpacingStepRow spacing; overrides `gap` for the row axis.
columnGap
SpacingStepColumn spacing; overrides `gap` for the column axis.
align
GridAlignment (default: 'stretch')Vertical alignment of items.
justify
GridAlignment (default: 'stretch')Horizontal alignment of items.
children
ReactNodeGrid content.
xstyle
StyleXStylesStyleX 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.
PropTypeDescription
columns
number | 'full'Columns to span; use `'full'` to span the entire row.
rows
numberRows to span.
children
ReactNodeContent.

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>
  );
}