Dither

A still image or gradient, redrawn in dots of the theme's colours.

SourcePackage @weft-js/warpPlayground

Preview

tsx

import { Dither } from '@weft-js/warp'export function Image() {  return (    <Dither src="/art/field.png" alt="A green and white landscape of soft shapes" ratio="16 / 10" cell={3} />  )}

Installation

npm install @weft-js/warp

Usage

tsx

import { Dither } from '@weft-js/warp'<Dither src="/art/field.png" alt="A green and white landscape of soft shapes" ratio="16 / 10" cell={3} />

A gradient

With no src, it dithers a soft gradient.

tsx

import { Dither } from '@weft-js/warp'export function Gradient() {  return (    <Dither gradient={SOFT} ramp="accent" ratio="21 / 9" />  )}const SOFT = { angle: 30 }

A radial gradient

from and to run from 0 to 1.

tsx

import { Dither } from '@weft-js/warp'export function Radial() {  return (    <Dither gradient={GLOW} ramp="info" ratio="21 / 9" label="A soft blue glow" />  )}const GLOW = { radial: true, from: 1, to: 0 }

Algorithms

Patterns stay steady and suit gradients. floyd and atkinson hold more detail in images.

tsx

import { Dither, Grid, Stack, Text } from '@weft-js/warp'export function Algorithms() {  return (    <Grid min="sm" cols={3} gap="related">      {ALGORITHMS.map(algorithm => (        <Stack key={algorithm} gap="tight">          <Dither gradient={SOFT} algorithm={algorithm} ratio="16 / 10" />          <Text subtle role="caption">{algorithm}</Text>        </Stack>      ))}    </Grid>  )}const min = 60_000const ALGORITHMS = ['bayer2', 'bayer8', 'blue', 'halftone', 'floyd', 'atkinson'] as constconst SOFT = { angle: 30 }

A status banner

Use gradient and ramp to shade a banner, and ratio to set its shape.

tsx

import { Button, Dither, Row, Stack, Text } from '@weft-js/warp'export function Banner() {  return (    <Stack gap="group">      <Dither gradient={SOFT} ramp="positive" ratio="5 / 1" />      <Row gap="related" justify="between">        <Stack gap="tight">          <Text role="heading">storefront is live</Text>          <Text subtle>Deployed by Priya Raman in 2 minutes.</Text>        </Stack>        <Button emphasis="outline" tone="neutral">View logs</Button>      </Row>    </Stack>  )}const SOFT = { angle: 30 }

When to use

Use it for

A picture should match the theme
A quiet textured band

Reach for something else

DitherField, when it should move

Playground

Algorithm

Ramp

Cell4

Invert

import { Dither } from '@weft-js/warp'<Dither />

Accessibility

An image keeps its alt. A gradient is decorative unless you give it a label.

API Reference

Prop	Type	Default	Description
`src`	`string`	—	An image to dither. The real <img> stays underneath, for alt text, for no script and for a cross-origin failure.
`alt`	`string`	—	The image's alt text, kept on the real <img> underneath.
`crossorigin`	`"anonymous" \| "use-credentials"`	—	The image's CORS mode. A cross-origin image needs it to be read and dithered.
`gradient`	`Gradient`	—	With no `src`: `{ angle, radial, from, to }`.
`algorithm`	`Algorithm`	—	`atkinson` by default for images, `bayer8` for gradients.
`ramp`	`Ramp`	—	The inks: a tone such as `accent`, or your own list of colours.
`cell`	`number`	—	CSS pixels per dither cell. Larger cells give a coarser, chunkier picture.
`inks`	`number`	—	How many inks of the ramp to use. Default: the tier's.
`contrast`	`number`	—	Tone contrast, around 1.
`invert`	`boolean`	`false`	Swaps light and dark.
`fill`	`boolean`	`false`	Fills the nearest positioned parent instead of keeping a ratio, for a section background.
`ratio`	`string \| number`	—	Width to height.
`label`	`string`	—	Its accessible name. Fields show it; icon-only controls speak it.

RelatedDither field Dither glyph