# radialGradient

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

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

Builds a `radial-gradient(...)` value string for any `background-image` use.
`shape` is the raw shape/size/position clause CSS expects, so a compound
clause such as `"ellipse at top left"` passes through unchanged.

## Quick reference

Every documented call, beside the CSS it emits.

| Call | CSS |
| --- | --- |
| `u.radialGradient("circle", "red", "blue")` | `"radial-gradient(circle, red, blue)"` |
| `u.radialGradient("circle at top left", { color: "red", position: "20%" }, "blue")` | `"radial-gradient(circle at top left, red 20%, blue)"` |

## Examples

### Basic example

Use `radialGradient` with a shape and two or more colors to build a gradient that spreads from a point:

```tsx
<div
	mix={[
		bg({
			image: radialGradient(
				"circle",
				"var(--ui-color-warning-300)",
				"var(--ui-color-brand-600)",
			),
		}),
		fg("brand.onSolid"),
		is(48),
		bs(32),
		...,
	]}
>
	circle
</div>
```

### Position

Add an `at` clause to the shape, like `circle at top left`, to move where the gradient starts:

```tsx
<div mix={[...]}>
	<div
		mix={[
			bg({
				image: radialGradient(
					"circle at top left",
					"var(--ui-color-warning-300)",
					"var(--ui-color-brand-600)",
				),
			}),
			fg("brand.onSolid"),
			is(48),
			bs(32),
			...,
		]}
	>
		circle at top left
	</div>
	<div
		mix={[
			bg({
				image: radialGradient(
					"ellipse at bottom",
					"var(--ui-color-warning-300)",
					"var(--ui-color-brand-600)",
				),
			}),
			fg("brand.onSolid"),
			is(48),
			bs(32),
			...,
		]}
	>
		ellipse at bottom
	</div>
</div>
```

### Extent

Name an extent, like `closest-side` or `farthest-corner`, to set how far the shape reaches before its last stop:

```tsx
<div mix={[...]}>
	<div
		mix={[
			bg({
				image: radialGradient(
					"circle closest-side",
					{ color: "var(--ui-color-brand-500)", position: "99%" },
					"var(--ui-color-brand-100)",
				),
			}),
			fg("brand.onSolid"),
			is(48),
			bs(32),
			...,
		]}
	>
		closest-side
	</div>
	<div
		mix={[
			bg({
				image: radialGradient(
					"circle farthest-corner",
					{ color: "var(--ui-color-brand-500)", position: "60%" },
					"var(--ui-color-brand-100)",
				),
			}),
			fg("brand.onSolid"),
			is(48),
			bs(32),
			...,
		]}
	>
		farthest-corner
	</div>
</div>
```

## Applying on a state

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

```ts
u.hover(u.radialGradient("circle", "red", "blue"))
```

## Responsive design

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

```ts
u.at("md", u.radialGradient("circle", "red", "blue"))
```

## Signature

```ts
u.radialGradient(shape: GradientShape, ...stops: GradientStop[])
```