# Grid

Equal columns or a grid that fits its available width.

```tsx
import { Grid } from "@/components/ui/grid"
import { Heading } from "@/components/ui/heading"
import { Text } from "@/components/ui/text"
import { VStack } from "@/components/ui/stack"

export default function GridDemo() {
  return (
    <Grid columns={2} gap={6}>
      <VStack gap={1}>
        <Heading>Production</Heading>
        <Text tone="muted">All services operational</Text>
      </VStack>
      <VStack gap={1}>
        <Heading>Preview</Heading>
        <Text tone="muted">Latest changes ready for review</Text>
      </VStack>
    </Grid>
  )
}
```

## Installation

**Command**

```bash
npx shadcn@latest add @arene/grid
```

Needs the [arene setup](https://www.arene.style/docs/installation) first.

**Manual**

1. Install the packages it imports:

   ```bash
   npm install @base-ui/react @stylexjs/stylex clsx
   ```

2. Set up the token layer. See [Installation](https://www.arene.style/docs/installation).
   Also copy the shared `lib/spacing.ts` helper used by [Stack](https://www.arene.style/docs/components/stack).

3. Copy the shared spacing helper and the component into your project.

   ```ts title="lib/spacing.ts"
   import * as stylex from "@stylexjs/stylex"

   import { space } from "@/theme/tokens.stylex"

   export const gapStyles = stylex.create({
     0: { columnGap: space.s0, rowGap: space.s0 },
     0.5: { columnGap: space.s0_5, rowGap: space.s0_5 },
     1: { columnGap: space.s1, rowGap: space.s1 },
     1.5: { columnGap: space.s1_5, rowGap: space.s1_5 },
     2: { columnGap: space.s2, rowGap: space.s2 },
     2.5: { columnGap: space.s2_5, rowGap: space.s2_5 },
     3: { columnGap: space.s3, rowGap: space.s3 },
     3.5: { columnGap: space.s3_5, rowGap: space.s3_5 },
     4: { columnGap: space.s4, rowGap: space.s4 },
     5: { columnGap: space.s5, rowGap: space.s5 },
     6: { columnGap: space.s6, rowGap: space.s6 },
     8: { columnGap: space.s8, rowGap: space.s8 },
     10: { columnGap: space.s10, rowGap: space.s10 },
     12: { columnGap: space.s12, rowGap: space.s12 },
     16: { columnGap: space.s16, rowGap: space.s16 },
     24: { columnGap: space.s24, rowGap: space.s24 },
   })

   export const paddingInlineStartStyles = stylex.create({
     0: { paddingInlineStart: space.s0 },
     0.5: { paddingInlineStart: space.s0_5 },
     1: { paddingInlineStart: space.s1 },
     1.5: { paddingInlineStart: space.s1_5 },
     2: { paddingInlineStart: space.s2 },
     2.5: { paddingInlineStart: space.s2_5 },
     3: { paddingInlineStart: space.s3 },
     3.5: { paddingInlineStart: space.s3_5 },
     4: { paddingInlineStart: space.s4 },
     5: { paddingInlineStart: space.s5 },
     6: { paddingInlineStart: space.s6 },
     8: { paddingInlineStart: space.s8 },
     10: { paddingInlineStart: space.s10 },
     12: { paddingInlineStart: space.s12 },
     16: { paddingInlineStart: space.s16 },
     24: { paddingInlineStart: space.s24 },
   })

   export const paddingInlineEndStyles = stylex.create({
     0: { paddingInlineEnd: space.s0 },
     0.5: { paddingInlineEnd: space.s0_5 },
     1: { paddingInlineEnd: space.s1 },
     1.5: { paddingInlineEnd: space.s1_5 },
     2: { paddingInlineEnd: space.s2 },
     2.5: { paddingInlineEnd: space.s2_5 },
     3: { paddingInlineEnd: space.s3 },
     3.5: { paddingInlineEnd: space.s3_5 },
     4: { paddingInlineEnd: space.s4 },
     5: { paddingInlineEnd: space.s5 },
     6: { paddingInlineEnd: space.s6 },
     8: { paddingInlineEnd: space.s8 },
     10: { paddingInlineEnd: space.s10 },
     12: { paddingInlineEnd: space.s12 },
     16: { paddingInlineEnd: space.s16 },
     24: { paddingInlineEnd: space.s24 },
   })

   export const paddingBlockStartStyles = stylex.create({
     0: { paddingBlockStart: space.s0 },
     0.5: { paddingBlockStart: space.s0_5 },
     1: { paddingBlockStart: space.s1 },
     1.5: { paddingBlockStart: space.s1_5 },
     2: { paddingBlockStart: space.s2 },
     2.5: { paddingBlockStart: space.s2_5 },
     3: { paddingBlockStart: space.s3 },
     3.5: { paddingBlockStart: space.s3_5 },
     4: { paddingBlockStart: space.s4 },
     5: { paddingBlockStart: space.s5 },
     6: { paddingBlockStart: space.s6 },
     8: { paddingBlockStart: space.s8 },
     10: { paddingBlockStart: space.s10 },
     12: { paddingBlockStart: space.s12 },
     16: { paddingBlockStart: space.s16 },
     24: { paddingBlockStart: space.s24 },
   })

   export const paddingBlockEndStyles = stylex.create({
     0: { paddingBlockEnd: space.s0 },
     0.5: { paddingBlockEnd: space.s0_5 },
     1: { paddingBlockEnd: space.s1 },
     1.5: { paddingBlockEnd: space.s1_5 },
     2: { paddingBlockEnd: space.s2 },
     2.5: { paddingBlockEnd: space.s2_5 },
     3: { paddingBlockEnd: space.s3 },
     3.5: { paddingBlockEnd: space.s3_5 },
     4: { paddingBlockEnd: space.s4 },
     5: { paddingBlockEnd: space.s5 },
     6: { paddingBlockEnd: space.s6 },
     8: { paddingBlockEnd: space.s8 },
     10: { paddingBlockEnd: space.s10 },
     12: { paddingBlockEnd: space.s12 },
     16: { paddingBlockEnd: space.s16 },
     24: { paddingBlockEnd: space.s24 },
   })

   type SpacingStep = keyof typeof gapStyles

   export type { SpacingStep }
   ```

   ```tsx title="components/ui/grid.tsx"
   "use client"

   import type { CSSProperties } from "react"
   import { useRender } from "@base-ui/react/use-render"
   import * as stylex from "@stylexjs/stylex"
   import type { StyleXStyles } from "@stylexjs/stylex"
   import { clsx } from "clsx"

   import { width } from "@/theme/tokens.stylex"
   import { gapStyles, type SpacingStep } from "@/lib/spacing"

   const styles = stylex.create({ base: { display: "grid", minWidth: 0 } })
   const columnsStyles = stylex.create({
     1: { gridTemplateColumns: "minmax(0, 1fr)" },
     2: { gridTemplateColumns: "repeat(2, minmax(0, 1fr))" },
     3: { gridTemplateColumns: "repeat(3, minmax(0, 1fr))" },
   })
   const autoFit = stylex.create({
     narrow: { gridTemplateColumns: `repeat(auto-fit, minmax(min(100%, ${width.narrow}), 1fr))` },
     xs: { gridTemplateColumns: `repeat(auto-fit, minmax(min(100%, ${width.xs}), 1fr))` },
   })
   const gridStyles = { base: styles.base, columns: columnsStyles, autoFit, gap: gapStyles }

   type GridProps = useRender.ComponentProps<"div"> & {
     gap?: SpacingStep
     xstyle?: StyleXStyles
     style?: CSSProperties
   } & (
       | { columns?: keyof typeof columnsStyles; minWidth?: never }
       | { columns?: never; minWidth: keyof typeof autoFit }
     )

   function Grid({
     render,
     ref,
     columns,
     minWidth,
     gap,
     xstyle,
     className,
     style,
     ...props
   }: GridProps) {
     const sx = stylex.props(
       styles.base,
       minWidth == null ? columnsStyles[columns ?? 1] : autoFit[minWidth],
       gap != null && gapStyles[gap],
       xstyle,
     )
     return useRender({
       defaultTagName: "div",
       render,
       ref,
       props: {
         "data-slot": "grid",
         ...sx,
         ...props,
         className: clsx(sx.className, className),
         style: { ...sx.style, ...style },
       },
     })
   }

   export { Grid, gridStyles, type GridProps }
   ```

4. Change the `@/` imports if your project uses different aliases.

## Usage

```tsx
import { Grid } from "@/components/ui/grid"
```

```tsx
<Grid columns={2} gap={4}>
  <div>Name</div>
  <div>Email</div>
</Grid>
```

Use `columns` for fixed equal columns. Use `minWidth` instead for auto-fit
columns with a minimum width in rem. A track never exceeds the available width,
so a narrow container does not overflow. The two modes are mutually exclusive.

`gap` uses the [Stack spacing scale](https://www.arene.style/docs/components/stack).
`gridStyles` exports `base`, `columns`, `autoFit` and `gap`.

## Columns

Choose one, two or three equal columns. With neither mode set, the grid has one column.

```tsx
import { Grid } from "@/components/ui/grid"
import { VStack } from "@/components/ui/stack"

export default function GridColumns() {
  return (
    <VStack gap={3}>
      <Grid columns={1} gap={2}>
        <div>Name</div>
        <div>Email</div>
        <div>Role</div>
      </Grid>
      <Grid columns={2} gap={2}>
        <div>Name</div>
        <div>Email</div>
        <div>Role</div>
      </Grid>
      <Grid columns={3} gap={2}>
        <div>Name</div>
        <div>Email</div>
        <div>Role</div>
      </Grid>
    </VStack>
  )
}
```

## Minimum width

Use `narrow` (12rem) or `xs` (20rem) for tracks that fit the available width.

```tsx
import { Grid } from "@/components/ui/grid"
import { VStack } from "@/components/ui/stack"

export default function GridMinWidth() {
  return (
    <VStack gap={3}>
      <Grid minWidth="narrow" gap={4}>
        <div>narrow: Project settings</div>
        <div>Team members</div>
      </Grid>
      <Grid minWidth="xs" gap={4}>
        <div>xs: Project settings</div>
        <div>Team members</div>
      </Grid>
    </VStack>
  )
}
```

## Gap

Gap is unset by default and uses the shared spacing scale.

```tsx
import { Grid } from "@/components/ui/grid"
import { VStack } from "@/components/ui/stack"

export default function GridGap() {
  return (
    <VStack gap={3}>
      <Grid columns={2} gap={0}>
        <div>Gap 0</div>
        <div>Preview</div>
      </Grid>
      <Grid columns={2} gap={0.5}>
        <div>Gap 0.5</div>
        <div>Preview</div>
      </Grid>
      <Grid columns={2} gap={1}>
        <div>Gap 1</div>
        <div>Preview</div>
      </Grid>
      <Grid columns={2} gap={1.5}>
        <div>Gap 1.5</div>
        <div>Preview</div>
      </Grid>
      <Grid columns={2} gap={2}>
        <div>Gap 2</div>
        <div>Preview</div>
      </Grid>
      <Grid columns={2} gap={2.5}>
        <div>Gap 2.5</div>
        <div>Preview</div>
      </Grid>
      <Grid columns={2} gap={3}>
        <div>Gap 3</div>
        <div>Preview</div>
      </Grid>
      <Grid columns={2} gap={3.5}>
        <div>Gap 3.5</div>
        <div>Preview</div>
      </Grid>
      <Grid columns={2} gap={4}>
        <div>Gap 4</div>
        <div>Preview</div>
      </Grid>
      <Grid columns={2} gap={5}>
        <div>Gap 5</div>
        <div>Preview</div>
      </Grid>
      <Grid columns={2} gap={6}>
        <div>Gap 6</div>
        <div>Preview</div>
      </Grid>
      <Grid columns={2} gap={8}>
        <div>Gap 8</div>
        <div>Preview</div>
      </Grid>
      <Grid columns={2} gap={10}>
        <div>Gap 10</div>
        <div>Preview</div>
      </Grid>
      <Grid columns={2} gap={12}>
        <div>Gap 12</div>
        <div>Preview</div>
      </Grid>
      <Grid columns={2} gap={16}>
        <div>Gap 16</div>
        <div>Preview</div>
      </Grid>
      <Grid columns={2} gap={24}>
        <div>Gap 24</div>
        <div>Preview</div>
      </Grid>
    </VStack>
  )
}
```

## Composition

Pass `render` to choose a semantic element. Put its props on that element.

```tsx
import { Grid } from "@/components/ui/grid"

export default function GridRender() {
  return (
    <Grid render={<section aria-label="Project details" />} columns={2} gap={4}>
      <div>Name: arene</div>
      <div>Status: active</div>
    </Grid>
  )
}
```

## API reference

See Base UI's [useRender reference](https://base-ui.com/react/utils/use-render)
for composition props. Native element props are forwarded.

| Prop        | Type                   | Default        |
| ----------- | ---------------------- | -------------- |
| `columns`   | `1 \| 2 \| 3`          | None           |
| `minWidth`  | `"narrow" \| "xs"`     | None           |
| `gap`       | `SpacingStep`          | None           |
| `render`    | `useRender.RenderProp` | Native element |
| `xstyle`    | `StyleXStyles`         | None           |
| `className` | `string`               | None           |
| `style`     | `CSSProperties`        | None           |

### Data attributes

| Attribute          | On   | Effect                   |
| ------------------ | ---- | ------------------------ |
| `data-slot="grid"` | root | Identifies the component |
