> ## Documentation Index
> Fetch the complete documentation index at: https://blacksilva.com/silva-ui/llms.txt
> Use this file to discover all available pages before exploring further.

# Theme-aware gradients

> Build custom gradients whose token stops follow the nearest Silva UI theme.

# Theme-aware gradients

Use `gradient` on `Box` when the stops should follow the nearest Silva UI theme. It is a compact, typed API for custom gradients that accepts semantic theme tokens, Radix colour tokens, or valid CSS colour values.

## Use semantic stops for UI meaning

Use semantic stops when a gradient has a UI role: `primary` and `primaryActive` follow the active theme, including a custom theme. Use named hue tokens such as `violet9` and `cyan9` for decorative accents. Literal CSS values are useful for one-off brand work, but remain fixed when the theme changes.

> [tab] Preview
>
> [Theme-aware gradient preview](https://black-silva.github.io/silva-ui/previews/?example=gradient-1)

> [tab] Code
>
> ```tsx theme={null}
> import { Box, Text, Theme } from "silva-ui"
>
> <Theme name="midnight">
>   <Box
>     gradient={{ from: "primary", via: "violet9", to: "cyan9", deg: 135 }}
>     borderRadius="large"
>     p="large"
>   >
>     <Text color="primaryContrast">Theme-aware gradient</Text>
>   </Box>
> </Theme>
> ```

## Choose the right gradient API

| Need | Use |
| - | - |
| A reusable, fixed visual treatment | Named `backgroundColor` or `color` value such as `aurora` or `ocean` |
| Custom stops that respond to a `Theme` or custom theme | `Box` with the `gradient` prop |

Named gradients and animation are documented in [Visuals](https://blacksilva.com/silva-ui/silva-ui/docs/foundations/visuals.md). Use `gradient` when a component needs its own colours, direction, or gradient type.

## Gradient options

`from` and `to` are required. `via`, `type`, and `deg` are optional.

| Property | Values | Default |
| - | - | - |
| `from` | theme token or CSS colour | required |
| `to` | theme token or CSS colour | required |
| `via` | theme token or CSS colour | none |
| `type` | `linear`, `radial`, `conic` | `linear` |
| `deg` | degrees for `linear` and `conic` gradients | `90` |

## Theme scopes update gradient stops

Token stops compile to Silva UI CSS variables. The gradient does not need to be rebuilt when its nearest `Theme` changes: its semantic values resolve in the new scope. The same applies to a custom Vanilla Extract theme that implements the Silva UI contract.

> [tab] Preview
>
> [Gradient across theme scopes preview](https://black-silva.github.io/silva-ui/previews/?example=gradient-2)

> [tab] Code
>
> ```tsx theme={null}
> <Theme name="light">
>   <Box gradient={{ from: "primary", to: "primaryHover" }} />
> </Theme>
>
> <Theme name="midnight">
>   <Box gradient={{ from: "primary", to: "primaryHover" }} />
> </Theme>
> ```

See [Theming](https://blacksilva.com/silva-ui/silva-ui/docs/theming.md) to define a custom theme contract.

### Custom theme example

A gradient inside a custom theme resolves through that wrapper just like `bg`, `color`, and component variants do.

> [tab] Preview
>
> [Custom theme gradient preview](https://black-silva.github.io/silva-ui/previews/?example=gradient-3)

> [tab] Code
>
> ```tsx theme={null}
> import { Box } from "silva-ui"
> import { brandTheme } from "./brand-theme.css"
>
> export function BrandBanner() {
>   return (
>     <section class={brandTheme}>
>       <Box
>         gradient={{ from: "primary", to: "primaryActive", deg: 135 }}
>         borderRadius="large"
>         p="large"
>       >
>         Brand-aware banner
>       </Box>
>     </section>
>   )
> }
> ```

## Gradient types

> [tab] Preview
>
> [Radial and conic gradient preview](https://black-silva.github.io/silva-ui/previews/?example=gradient-4)

> [tab] Code
>
> ```tsx theme={null}
> <Box gradient={{ type: "radial", from: "primary", to: "background" }} />
>
> <Box gradient={{ type: "conic", from: "violet9", to: "cyan9", deg: 45 }} />
> ```

`deg` changes the direction of linear gradients and the start angle of conic gradients. Radial gradients ignore it.

## Reuse the generated CSS

Use `gradientToCss` when a wrapper component or a plain element needs the exact same theme-aware `background-image` value.

```ts theme={null}
import { gradientToCss } from "silva-ui"

const backgroundImage = gradientToCss({
  from: "primary",
  to: "cyan9",
  deg: 135,
})
```

For CSS capabilities beyond the compact API, use `style` directly:

```tsx theme={null}
<Box
  style={{
    backgroundImage: "repeating-linear-gradient(45deg, #fff 0 10px, #f1f5f9 10px 20px)",
  }}
/>
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.