---
title: "Gap"
description: "Space the children of a grid or flex container with the token gap scale, gap-none to gap-3xl."
url: https://docs.systhema.app/next/styling/gap
version: unreleased (main)
docs_index: https://docs.systhema.app/next/llms.txt
---

The gap utilities set `gap`, `column-gap` and `row-gap` from the token gap scale, so every stack, row and grid on a site shares the same rhythm. With the default tokens the sizes are `none`, `xs`, `sm`, `md`, `lg`, `xl`, `2xl` and `3xl`.

## Quick reference

<!-- generated:utilities gap -->

| Class        | Styles                         |
| ------------ | ------------------------------ |
| `gap-none`   | `gap: var(--gap-none);`        |
| `gap-x-none` | `column-gap: var(--gap-none);` |
| `gap-y-none` | `row-gap: var(--gap-none);`    |
| `gap-xs`     | `gap: var(--gap-xs);`          |
| `gap-x-xs`   | `column-gap: var(--gap-xs);`   |
| `gap-y-xs`   | `row-gap: var(--gap-xs);`      |
| `gap-sm`     | `gap: var(--gap-sm);`          |
| `gap-x-sm`   | `column-gap: var(--gap-sm);`   |
| `gap-y-sm`   | `row-gap: var(--gap-sm);`      |
| `gap-md`     | `gap: var(--gap-md);`          |
| `gap-x-md`   | `column-gap: var(--gap-md);`   |
| `gap-y-md`   | `row-gap: var(--gap-md);`      |
| `gap-lg`     | `gap: var(--gap-lg);`          |
| `gap-x-lg`   | `column-gap: var(--gap-lg);`   |
| `gap-y-lg`   | `row-gap: var(--gap-lg);`      |
| `gap-xl`     | `gap: var(--gap-xl);`          |
| `gap-x-xl`   | `column-gap: var(--gap-xl);`   |
| `gap-y-xl`   | `row-gap: var(--gap-xl);`      |
| `gap-2xl`    | `gap: var(--gap-2xl);`         |
| `gap-x-2xl`  | `column-gap: var(--gap-2xl);`  |
| `gap-y-2xl`  | `row-gap: var(--gap-2xl);`     |
| `gap-3xl`    | `gap: var(--gap-3xl);`         |
| `gap-x-3xl`  | `column-gap: var(--gap-3xl);`  |
| `gap-y-3xl`  | `row-gap: var(--gap-3xl);`     |

<!-- /generated -->

## Basic usage

Add `gap-{size}` to a grid or flex container to space its children. The hatched area in these previews is the gap.

```tsx preview iframe height=260 title="gap-md"
const hatch =
  'bg-[repeating-linear-gradient(315deg,var(--color-foundations-line-muted)_0_1px,transparent_0_50%)] bg-size-[10px_10px]'

export default function Demo() {
  return (
    <div className={`grid w-full grid-cols-2 gap-md rounded-lg ${hatch}`}>
      {['01', '02', '03', '04'].map((label) => (
        <div
          key={label}
          className="bg-theme-500 grid h-14 place-items-center rounded-lg font-mono text-sm text-white"
        >
          {label}
        </div>
      ))}
    </div>
  )
}
```

### Row and column gaps

Use `gap-x-{size}` and `gap-y-{size}` to set the column gap and the row gap separately.

```tsx preview iframe height=280 title="gap-x-xl gap-y-xs"
const hatch =
  'bg-[repeating-linear-gradient(315deg,var(--color-foundations-line-muted)_0_1px,transparent_0_50%)] bg-size-[10px_10px]'

export default function Demo() {
  return (
    <div className={`grid w-full grid-cols-3 gap-x-xl gap-y-xs rounded-lg ${hatch}`}>
      {['01', '02', '03', '04', '05', '06'].map((label) => (
        <div
          key={label}
          className="bg-theme-500 grid h-14 place-items-center rounded-lg font-mono text-sm text-white"
        >
          {label}
        </div>
      ))}
    </div>
  )
}
```

### The whole scale

Each row below is a flex container with one gap size between two boxes.

```tsx preview iframe height=520 title="Gap scale"
const hatch =
  'bg-[repeating-linear-gradient(315deg,var(--color-foundations-line-muted)_0_1px,transparent_0_50%)] bg-size-[10px_10px]'

const sizes = ['gap-none', 'gap-xs', 'gap-sm', 'gap-md', 'gap-lg', 'gap-xl', 'gap-2xl', 'gap-3xl']

export default function Demo() {
  return (
    <div className="flex w-full flex-col gap-3">
      {sizes.map((size) => (
        <div key={size} className="flex items-center gap-4">
          <span className="color-label w-20 shrink-0 font-mono text-xs">{size}</span>
          <div className={`flex rounded-md ${size} ${hatch}`}>
            <div className="bg-theme-500 h-8 w-12 rounded-md" />
            <div className="bg-theme-500 h-8 w-12 rounded-md" />
          </div>
        </div>
      ))}
    </div>
  )
}
```

### In components

The `gap` prop of [`Stack`](https://docs.systhema.app/next/components/stack.md) and [`Columns`](https://docs.systhema.app/next/components/columns.md) takes the same size names and renders these classes, so you rarely write them by hand inside a page built from components.

## Responsive and state variants

Each size is a `responsiveSizing` token, so its value changes per breakpoint on its own. With the default tokens `gap-md` is 32px on `sm`, 24px on `md` and 40px on `lg` (the full table is in [Spacing and sizing](https://docs.systhema.app/next/reference/tokens/spacing.md#gap)). The [Payload template](https://docs.systhema.app/next/getting-started/templates/payload.md) and these docs also apply a fluid spacing rule to `gap`, so the value scales with the viewport between breakpoints; switch the preview below between device widths to see it.

To pick a different size per breakpoint, prefix the class with a breakpoint:

```tsx preview iframe height=300 title="gap-xs md:gap-md lg:gap-2xl"
const hatch =
  'bg-[repeating-linear-gradient(315deg,var(--color-foundations-line-muted)_0_1px,transparent_0_50%)] bg-size-[10px_10px]'

export default function Demo() {
  return (
    <div className={`grid w-full grid-cols-3 gap-xs rounded-lg md:gap-md lg:gap-2xl ${hatch}`}>
      {['01', '02', '03', '04', '05', '06'].map((label) => (
        <div
          key={label}
          className="bg-theme-500 grid h-14 place-items-center rounded-lg font-mono text-sm text-white"
        >
          {label}
        </div>
      ))}
    </div>
  )
}
```

State variants (`hover:`, `focus-within:`, `group-hover:`) work the same way, though a changing gap is rarely what you want.

The gap classes sit in Systhema's `utilities.systhema` sub-layer, so a Tailwind spacing utility such as `gap-4` on the same element wins over `gap-md`. See [Cascade layers](https://docs.systhema.app/next/styling/cascade-layers.md).

## Customizing

The scale comes from the `gap` group of the `responsiveSizing` collection: `gap-md` reads `--gap-md`, and so on. Change a value per breakpoint in Figma, or override it with `customTokens.responsiveSizing`:

```ts title="systhema.config.ts"
const config: SysthemaConfig = {
  customTokens: {
    responsiveSizing: {
      lg: { gap: { md: '48px' } },
    },
  },
}
```

A key you add to the group becomes a class of the same name. Add it to every breakpoint so it has a value everywhere:

```ts title="systhema.config.ts"
const config: SysthemaConfig = {
  customTokens: {
    responsiveSizing: {
      sm: { gap: { '4xl': '128px' } },
      md: { gap: { '4xl': '128px' } },
      lg: { gap: { '4xl': '160px' } },
    },
  },
}
```

That emits `gap-4xl`, `gap-x-4xl` and `gap-y-4xl`. How pixel values become CSS (fixed `--spacing` multiples or fluid `vw`) is set by the `spacing` option; see [Responsive sizing](https://docs.systhema.app/next/concepts/responsive-sizing.md#spacing-rules). Turn the whole family off with `blocks.gap: false` ([Component CSS blocks](https://docs.systhema.app/next/styling/blocks.md)).

## Related

- [Spacing and sizing tokens](https://docs.systhema.app/next/reference/tokens/spacing.md#gap)
- [Stack](https://docs.systhema.app/next/components/stack.md)
- [Columns](https://docs.systhema.app/next/components/columns.md)
- [Flex grid](https://docs.systhema.app/next/styling/flex-grid.md)