# when

> The primitive selector wrapper every other state wrapper (`hover()`, `checked()`, ...) is sugar over.

```ts
import { when } from "@sdxc/u/state";
```

The primitive selector wrapper every other state wrapper (`hover()`,
`checked()`, ...) is sugar over. `selector` must start with `&`, `@`, `:`,
`[`, or `.`; see checkNestedSelector for what happens otherwise.

## Quick reference

Every documented call, beside the CSS it emits.

| Call | CSS |
| --- | --- |
| `u.when("&:has(input:checked)", [u.bg("brand.tint"), u.border("brand")])` | `css({ "&:has(input:checked)": { backgroundColor: "...", borderColor: "..." } })` |

## Examples

### Basic example

Pass any nested selector starting with `&` to `when()` for a state no named wrapper covers, like odd rows:

```tsx
<ul mix={[is("100%"), overflow("clip"), ...]}>
	<li mix={[p(2, 3), when("&:nth-child(odd)", bg("brand.tint")), ...]}>
		Alice — Admin
	</li>
	<li mix={[p(2, 3), when("&:nth-child(odd)", bg("brand.tint")), ...]}>
		Bob — Editor
	</li>
	<li mix={[p(2, 3), when("&:nth-child(odd)", bg("brand.tint")), ...]}>
		Carol — Viewer
	</li>
	<li mix={[p(2, 3), when("&:nth-child(odd)", bg("brand.tint")), ...]}>
		Dan — Viewer
	</li>
</ul>
```

### At-rules

`when()` also takes an at-rule like `@media`. Nest `hover()` in it so the hover style only applies where a pointer can hover:

```tsx
<button
	type="button"
	mix={[
		bg("brand.solid"),
		fg("brand.onSolid"),
		when("@media (hover: hover)", hover(bg("color.brand.800"))),
		cursor("pointer"),
		...,
	]}
>
	Hover me
</button>
```

### Styling children

Start the selector with `& >` to reach an element's children, like spacing every item after the first:

```tsx
<div mix={[when("& > * + *", mbs(4)), ...]}>
	<div mix={[...]}>1</div>
	<div mix={[...]}>2</div>
	<div mix={[...]}>3</div>
</div>
```

```ts
u.when(":is(input:checked) ~ &", u.bg("brand.solid"))
```

## Responsive design

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

```ts
u.at("md", u.when("&:has(input:checked)", [u.bg("brand.tint"), u.border("brand")]))
```

## Signature

```ts
u.when(selector: string, input: UtilityInput<Node>)
```