import { SimpleGrid } from '@uhg-abyss/web/ui/SimpleGrid';

cols

gap

rowGap

() => {
  const ExampleBox = useMemo(() => {
    return styled('div', {
      static: {
        padding: '$web.semantic.spacing.scale.lg',
        borderRadius: '$web.semantic.border-radius.container.large',
        backgroundColor: '$web.semantic.color.surface.container.primary',
        color: '$web.semantic.color.text.content.primary-alt',
      },
    });
  }, []);

  return (
    <SimpleGrid cols={3}>
      {Array.from({ length: 6 }, (_, i) => {
        return <ExampleBox key={i + 1}>{i + 1}</ExampleBox>;
      })}
    </SimpleGrid>
  );
};

Cols

Use the cols prop to set the number of columns. This corresponds to the CSS grid-template-columns value. This accepts a number or a responsive object. Defaults to 1.

Gap and row gap

gap sets spacing for both rows and columns. Set rowGap to override vertical spacing independently. Both accept responsive objects.

Responsive props

In the default type="viewport" mode, cols, gap, and rowGap all accept a responsive object keyed by breakpoint (xs, sm, md, lg). Each key applies at its min-width and above.

In the example below, cols={{ xs: 1, sm: 2, md: 3, lg: 4 }} means:

• 1 column below sm (< 360px)
• 2 columns from sm to md (≥ 360px and < 744px)
• 3 columns from md to lg (≥ 744px and < 1248px)
• 4 columns from lg up (≥ 1248px)

gap and rowGap follow the same logic: column spacing tightens on small screens and row spacing opens up on larger ones.

Breakpoint keys pull their pixel values from the theme's breakpoints (sm = 360px, md = 744px, lg = 1248px by default), and a createTheme override is honored — in type="viewport" mode only. See Container queries for type="container".

Container queries

Set type="container" to make columns respond to the container's width instead of the viewport's. The component handles container-type: inline-size automatically. Use this when the grid is inside any context where the container width differs from the viewport, such as a resizable panel, drawer, or sidebar.

A container's width has no relation to the app's viewport breakpoints, so cols does not accept the named sm/md/lg breakpoints here. Use xs for the base value plus arbitrary pixel-width keys instead, e.g. cols={{ xs: 1, '300px': 2, '500px': 3 }}. Width keys can be declared in any order — they're always applied ascending — and they're always the literal pixel values you write, never affected by createTheme breakpoint overrides.

gap and rowGap still use the named breakpoints (xs/sm/md/lg), e.g. gap={{ xs: 'sm', md: 'lg' }}, resolved as @container queries at the fixed default pixel values rather than the live theme.

Auto-fill columns

Set minColWidth to let the grid automatically create as many columns as fit while keeping each column at least that wide. When minColWidth is set, cols is ignored.

Auto-fill vs. auto-fit

When using minColWidth, the grid creates as many columns as fit. The difference is what happens with leftover space:

• auto-fill (default) — Creates columns even if empty. Each item stays at its minimum width with extra space left over. Use when you want predictable column widths.
• auto-fit — Collapses empty columns and items stretch to fill available space. Use when you want items to grow and distribute evenly.

Auto rows

Use autoRows to control the size of implicitly created rows via CSS grid-auto-rows. Useful when all rows should share the same minimum height.

SimpleGrid Props

Name	Type	Default	Required	Description
asElement	string | undefined	'div'	-	Determine what type of html element the grid will render
autoFlow	'auto-fill' | 'auto-fit' | undefined	'auto-fill'	-	Controls the auto-placement algorithm used when minColWidth is set. - 'auto-fill' (default): creates as many tracks as fit, leaving empty tracks if items don't fill the row. - 'auto-fit': collapses empty tracks so items stretch to fill the row.
autoRows	string | undefined	-	-	CSS grid-auto-rows — controls the size of implicitly created rows. Useful when all rows should share the same height. Accepts any valid CSS value (e.g. 'minmax(100px, auto)').
children	React.ReactNode | undefined	-	-	The elements to lay out in equal-width columns. Rendered as-is.
cols	Responsive<number> | ContainerResponsive<number> | undefined	1	-	The number of equal-width columns. Accepts a responsive object, e.g. { xs: 1, sm: 2, md: 4 }. The number of equal-width columns. Accepts a responsive object keyed by xs and/or pixel widths, e.g. { xs: 1, '500px': 2 }.
gap	Responsive<Abyss.Space> | undefined	'$web.semantic.spacing.scale.lg'	-	The space between rows and columns. Accepts a token (e.g. $web.semantic.spacing.scale.lg), a raw CSS length, or a responsive object keyed by the named breakpoints (xs/sm/md/lg).
minColWidth	string | number | undefined	-	-	Minimum column width for auto-fill layout. When set, cols is ignored and the grid creates as many columns as fit while keeping each column at least this wide. Accepts any CSS length (e.g. '200px', '12rem').
rowGap	Responsive<Abyss.Space> | undefined	-	-	Overrides gap for vertical spacing between rows. Accepts a token (e.g. $web.semantic.spacing.scale.lg), a raw CSS length, or a responsive object keyed by the named breakpoints (xs/sm/md/lg).
type	'viewport' | 'container' | undefined	'viewport'	-	Column count responds to the viewport's width. Column count responds to the parent container's width instead of the viewport. The component wraps itself in a container-type: inline-size element automatically.

Below are the link(s) to the relevant GitHub type files:

Abyss.d.ts

SimpleGrid.types.ts

SimpleGrid Classes

Class Name	Description
.abyss-simple-grid-root	SimpleGrid root element