# scroll-margin

> Applies logical `scroll-margin` on a scroll item, growing the box the container aligns when it snaps to this item or an anchor jump targets it, so a sticky header clears only the items that need the extra room.

```ts
import { scrollMargin } from "@sdxc/u/overflow";
```

Applies logical `scroll-margin` on a scroll item, growing the box the
container aligns when it snaps to this item or an anchor jump targets it, so
a sticky header clears only the items that need the extra room.

- [MDN: logical properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_logical_properties_and_values)

## Quick reference

Every documented call, beside the CSS it emits.

| Call | CSS |
| --- | --- |
| `u.scrollMargin(4)` | `css({ scrollMargin: "calc(var(--ui-spacing, 0.25rem) * 4)" })` |
| `u.scrollMargin(16, 0)` | `css({ scrollMarginBlock: "...", scrollMarginInline: "..." })` |

## Examples

### Basic example

Use `scrollMargin(n)` on the targets of an anchor jump to land them clear of a sticky header. Click a link and the section stops below the header:

```tsx
<div mix={[vstack({ gap: 4 }), is(72), maxIs("100%")]}>
	<nav mix={[hstack({ gap: 3 })]}>
		<a href="#margined-1">Section 1</a>
		<a href="#margined-2">Section 2</a>
		<a href="#margined-3">Section 3</a>
	</nav>
	<div mix={[scroll("y"), vstack({ gap: 3 }), bs(56), pi(4), pbe(4), ...]}>
		<header mix={[sticky(), insBs(0), bg(), p(3), ...]}>Sticky header</header>
		<section id="margined-1" mix={[scrollMargin(14), shrink(), bs(32), ...]}>
			Section 1
		</section>
		<section id="margined-2" mix={[scrollMargin(14), shrink(), bs(32), ...]}>
			Section 2
		</section>
		<section id="margined-3" mix={[scrollMargin(14), shrink(), bs(32), ...]}>
			Section 3
		</section>
	</div>
</div>
```

### Insetting snapped items

Pass a block and an inline value, like `scrollMargin(0, 8)`, to grow the area each item snaps by. Scroll the row and each card settles away from the edge:

```tsx
<div
	mix={[
		scroll("x"),
		scrollSnapType(),
		hstack({ gap: 4 }),
		is(96),
		maxIs("100%"),
		p(4),
		...,
	]}
>
	<div mix={[scrollSnapAlign(), scrollMargin(0, 8), shrink(), is(56), bs(32), ...]}>
		1
	</div>
	<div mix={[scrollSnapAlign(), scrollMargin(0, 8), shrink(), is(56), bs(32), ...]}>
		2
	</div>
	<div mix={[scrollSnapAlign(), scrollMargin(0, 8), shrink(), is(56), bs(32), ...]}>
		3
	</div>
	<div mix={[scrollSnapAlign(), scrollMargin(0, 8), shrink(), is(56), bs(32), ...]}>
		4
	</div>
</div>
```

## Using a custom value

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

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

## Applying on a state

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

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

## Responsive design

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

```ts
u.at("md", u.scrollMargin(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
scrollMargin(4)
```

## Signature

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