# gap

> Applies `gap` using the spacing scale or a raw CSS length.

```ts
import { gap } from "@sdxc/u/layout";
```

Applies `gap` using the spacing scale or a raw CSS length. One value
applies to both the row and column gap; two values are read as
`"{row} {column}"`.

## Quick reference

Every documented call, beside the CSS it emits.

| Call | CSS |
| --- | --- |
| `u.gap(4)` | `css({ gap: "calc(var(--ui-spacing, 0.25rem) * 4)" })` |
| `u.gap(2, 4)` | `css({ gap: "calc(var(--ui-spacing, 0.25rem) * 2) calc(var(--ui-spacing, 0.25rem) * 4)" })` |

## Examples

### Basic example

Use `gap(n)` with a step of the spacing scale, like `gap(4)` or `gap(8)`, to space the rows and columns of a grid or flex container:

```tsx
<div mix={[grid(), gridTemplate({ columns: repeat(2, 1) }), gap(4), is(80), ...]}>
	<div mix={[...]}>01</div>
	<div mix={[...]}>02</div>
	<div mix={[...]}>03</div>
	<div mix={[...]}>04</div>
</div>
```

### Row and column gaps

Pass two values to set the row gap and then the column gap, like `gap(2, 8)`:

```tsx
<div mix={[grid(), gridTemplate({ columns: repeat(3, 1) }), gap(2, 8), is(96), ...]}>
	<div mix={[...]}>01</div>
	<div mix={[...]}>02</div>
	<div mix={[...]}>03</div>
	<div mix={[...]}>04</div>
	<div mix={[...]}>05</div>
	<div mix={[...]}>06</div>
</div>
```

### Spacing a wrapping row

`gap()` works in flex containers too, spacing items along each line and the lines that wrap:

```tsx
<ul mix={[flex(), flexWrap(), gap(2), is(80), m(0), p(0), listStyle("none")]}>
	<li mix={[...]}>layout</li>
	<li mix={[...]}>size</li>
	<li mix={[...]}>color</li>
	<li mix={[...]}>typography</li>
	<li mix={[...]}>effects</li>
	<li mix={[...]}>overflow</li>
</ul>
```

## Using a custom value

Every scale argument also takes a raw CSS value, which passes through untouched.

```ts
u.gap("2.75rem")
```

## Applying on a state

Wrap the call in a state utility to scope it to one selector.

```ts
u.hover(u.gap(4))
```

## Responsive design

Wrap the call in a container query to scope it to one width.

```ts
u.at("md", u.gap(4))
```

## Customizing your theme

### Customizing spacing

Every numeric step multiplies `--ui-spacing`, so redefining it rescales every spacing and sizing utility at once:

```css
:root {
	--ui-spacing: 0.25rem;
}
```

Every call that names the step now reads the new value:

```ts
gap(4)
```

## Signature

```ts
u.gap(...values: SpacingValue[])
```