# Dither gradient

A linear, radial or conic gradient drawn as a dither, for heroes, section breaks and cards.

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown variants are available by appending `.md` to any URL or sending an `Accept: text/markdown` header. The dithercn agent skill, for building any dither on the engine, is at [/.well-known/agent-skills/dithercn/SKILL.md](/.well-known/agent-skills/dithercn/SKILL.md).

<ComponentPreview src="examples/dither-gradient-demo.tsx" size="full" align="stretch" controls="ditherGradientControls">
  <DitherGradientDemo />
</ComponentPreview>

## Installation [#installation]

<InstallBlock name="dither-gradient" />

## Usage [#usage]

```tsx
import { DitherGradient } from "@/components/dithercn/dither-gradient";

export function Hero() {
  return (
    <section className="relative isolate min-h-[480px]">
      <DitherGradient angle={160} className="absolute inset-0 -z-10" />
      <h1>Your headline</h1>
    </section>
  );
}
```

The gradient fills its box, so give it a size with `className`. It runs from paper at the start to ink at the end, in your theme's `--dither-paper` and `--dither-ink` colours.

## Examples [#examples]

### Glow behind a headline [#glow-behind-a-headline]

A radial gradient that starts as ink and fades to paper. With the centre below the bottom edge and a small radius, only a low arc of light shows, and the headline sits on clean paper.

<ComponentPreview src="examples/dither-gradient-radial.tsx" size="lg" align="stretch">
  <DitherGradientRadial />
</ComponentPreview>

### Conic sweep through a palette [#conic-sweep-through-a-palette]

`palette` takes any number of colours from paper to ink. A conic sweep jumps from its last colour back to its first, so this palette starts and ends on the background to hide the seam. Blue noise gives it an even, grainy texture.

<ComponentPreview src="examples/dither-gradient-conic.tsx" size="lg" align="stretch">
  <DitherGradientConic />
</ComponentPreview>

### Still, inside a card [#still-inside-a-card]

With `animate={false}` the gradient draws one frame and stops. `to={0.55}` keeps the densest band light enough for text to sit on, and setting `--dither-paper` to the card's own background blends the gradient into it.

<ComponentPreview src="examples/dither-gradient-static.tsx">
  <DitherGradientStatic />
</ComponentPreview>

## Props [#props]

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `mode` | `"linear" \| "radial" \| "conic"` | `"linear"` | The gradient's shape. |
| `angle` | `number` | `180 (linear), 0 (conic)` | Linear: the direction in degrees, as in CSS. Conic: where the sweep starts. |
| `center` | `[x: number, y: number]` | `[0.5, 0.5]` | Radial and conic only. The centre as fractions of the box, measured from the top left. |
| `radius` | `number` | `1` | Radial only. 1 reaches the farthest corner. |
| `from` | `number` | `0` | Tone at the start, from 0 (paper) to 1 (ink). |
| `to` | `number` | `1` | Tone at the end. |
| `noise` | `number` | `0.12` | How far a slow noise drift bends the bands. 0 gives straight, even bands. |
| `palette` | `[DitherColor, DitherColor, ...DitherColor[]]` | `["--dither-paper", "--dither-ink"]` | Colours from paper to ink: palette names such as "green", CSS variable names or any CSS colour. |
| `matrix` | `"bayer2" \| "bayer4" \| "bayer8" \| "blue-noise"` | `"bayer4"` | The threshold pattern. See Dither engine. |
| `levels` | `number` | `All the matrix can draw` | Tones the gradient snaps to before dithering. Lower values give visible bands. |
| `cell` | `number` | `--dither-cell` | Size of one dither cell in CSS pixels. |
| `speed` | `number` | `1` | How fast the noise drifts. |
| `animate` | `boolean` | `true` | false draws one still frame. |
| `className` | `string` | `–` | Size and position. The gradient fills this box. |

## Notes [#notes]

* The gradient is decorative and hidden from assistive technology. Put real text on top of it, not inside it.
* With reduced motion turned on, it draws one still frame and stops.
* It pauses when scrolled out of view or when the tab is hidden, and releases its WebGL context when far offscreen. Without WebGL it shows a smooth CSS gradient in the same colours.
* One gradient costs one small draw per frame at 30 fps, at one pixel per dither cell. See [Performance](/docs/engine/performance).