# linearGradient

> Builds a `linear-gradient(...)` value string for any `background-image` use.

```ts
import { linearGradient } from "@sdxc/u/color";
```

Builds a `linear-gradient(...)` value string for any `background-image` use.
A numeric `angle` is treated as degrees; a string passes through unchanged,
so CSS's own side/corner keywords work too.

## Quick reference

Every documented call, beside the CSS it emits.

| Call | CSS |
| --- | --- |
| `u.linearGradient(45, "red", "blue")` | `"linear-gradient(45deg, red, blue)"` |
| `u.linearGradient("to right", { color: "red", position: "20%" }, "blue")` | `"linear-gradient(to right, red 20%, blue)"` |

## Examples

### Basic example

Use `linearGradient` with a direction and two or more colors to build a gradient for a background image:

```tsx
<div
	mix={[
		bg({
			image: linearGradient(
				"to right",
				"var(--ui-color-brand-500)",
				"var(--ui-color-danger-400)",
			),
		}),
		fg("brand.onSolid"),
		...,
	]}
>
	linearGradient("to right", ...)
</div>
```

### Angles

Pass a number of degrees, like `45`, or a side or corner keyword, like `to bottom right`, to set the direction:

```tsx
<div mix={[...]}>
	<div
		mix={[
			bg({
				image: linearGradient(0, "var(--ui-color-brand-500)", "var(--ui-color-success-400)"),
			}),
			fg("brand.onSolid"),
			...,
		]}
	>
		0
	</div>
	<div
		mix={[
			bg({
				image: linearGradient(45, "var(--ui-color-brand-500)", "var(--ui-color-success-400)"),
			}),
			fg("brand.onSolid"),
			...,
		]}
	>
		45
	</div>
	<div
		mix={[
			bg({
				image: linearGradient(90, "var(--ui-color-brand-500)", "var(--ui-color-success-400)"),
			}),
			fg("brand.onSolid"),
			...,
		]}
	>
		90
	</div>
	<div
		mix={[
			bg({
				image: linearGradient(
					"to bottom right",
					"var(--ui-color-brand-500)",
					"var(--ui-color-success-400)",
				),
			}),
			fg("brand.onSolid"),
			...,
		]}
	>
		to bottom right
	</div>
</div>
```

### Color stops

Pass a stop as an object with a `position`, like `20%`, to place it; two stops at one position draw a hard edge:

```tsx
<div
	mix={[
		bg({
			image: linearGradient(
				"to right",
				{ color: "var(--ui-color-brand-500)", position: "20%" },
				{ color: "var(--ui-color-warning-400)", position: "60%" },
				{ color: "var(--ui-color-danger-500)", position: "60%" },
			),
		}),
		fg("brand.onSolid"),
		is(96),
		...,
	]}
>
	20% · 60% · 60%
</div>
```

## Applying on a state

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

```ts
u.hover(u.linearGradient(45, "red", "blue"))
```

## Responsive design

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

```ts
u.at("md", u.linearGradient(45, "red", "blue"))
```

## Signature

```ts
u.linearGradient(angle: number | GradientDirection, ...stops: GradientStop[])
```