# shadow

> Applies a box shadow from the shadow scale, written to the `elevation` slot of the shared composite `boxShadow` declaration.

```ts
import { shadow } from "@sdxc/u/effects";
```

Applies a box shadow from the shadow scale, written to the `elevation` slot
of the shared composite `boxShadow` declaration. Claiming only that slot lets
an elevation shadow and a `u.ringShadow()` render as two stacked layers.
`"none"` clears the slot, and a raw CSS shadow passes through as written.

## Quick reference

Every documented call, beside the CSS it emits.

| Call | CSS |
| --- | --- |
| `u.shadow("lg")` | `css({ "--ui-box-shadow-elevation": "var(--ui-shadow-lg, 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1))", boxShadow: "var(--ui-box-shadow-ring, 0 0 #0000), var(--ui-box-shadow-elevation, 0 0 #0000)" })` |

## Examples

### Basic example

Use `shadow("sm")`, `shadow("md")`, `shadow("lg")` or `shadow("xl")` to give an element a box shadow from the shadow scale:

```tsx
<div mix={[...]}>
	<div mix={[shadow("sm"), ...]}>shadow("sm")</div>
	<div mix={[shadow("md"), ...]}>shadow("md")</div>
	<div mix={[shadow("lg"), ...]}>shadow("lg")</div>
	<div mix={[shadow("xl"), ...]}>shadow("xl")</div>
</div>
```

### Lifting on hover

Override the step with `hover(shadow("xl"))` to lift an element when it's hovered. Hover the card:

```tsx
<a
	href="/articles/latest"
	mix={[
		shadow("sm"),
		hover(shadow("xl")),
		transition("box-shadow", { duration: 200 }),
		...,
	]}
>
	Read the full article
</a>
```

## Applying on a state

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

```ts
u.hover(u.shadow("lg"))
```

## Responsive design

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

```ts
u.at("md", u.shadow("lg"))
```

## Customizing your theme

### Customizing shadows

Redefine a `--ui-shadow-*` variable to change a step, or declare a new one:

```css
:root {
	--ui-shadow-2xl: 0 25px 50px -12px rgb(0 0 0 / 0.25);
}
```

```ts
declare module "@sdxc/u" {
	interface Shadows {
		"2xl": true;
	}
}
```

The new name is then accepted wherever the scale is:

```ts
shadow("2xl")
```

## Signature

```ts
u.shadow(name?: ShadowName | (string & {}))
```