Skip to content
weftGitHub

DitherField

A moving dithered texture for backgrounds, in the theme's colours.

SourcePackage @weft-js/warpPlayground

Preview

tsx
import { Button, DitherField, Heading, Inset, Stack, Text } from '@weft-js/warp'export function Hero() {  return (    <DitherField kind="weave" fade="left" ratio="21 / 9">      <Inset pad="section">        <Stack gap="group" align="start">          <Heading>Deploys that stay out of the way</Heading>          <Text subtle>Push to main. weft builds, tests and ships it.</Text>          <Button icon="rocket">Start a project</Button>        </Stack>      </Inset>    </DitherField>  )}

Installation

npm install @weft-js/warp

Usage

tsx
import { DitherField } from '@weft-js/warp'<DitherField kind="weave" fade="left" ratio="21 / 9">  <Inset pad="section">    <Stack gap="group" align="start">      <Heading>Deploys that stay out of the way</Heading>      <Text subtle>Push to main. weft builds, tests and ships it.</Text>      <Button icon="rocket">Start a project</Button>    </Stack>  </Inset></DitherField>

Kinds

Five named fields, and the last is your own function of x, y and time.

tsx
import { DitherField, Grid } from '@weft-js/warp'export function Kinds() {  return (    <Grid min="sm" cols={3} gap="related">      {KINDS.map(kind => <DitherField key={kind} kind={kind} ratio="16 / 10" />)}      <DitherField kind={stripes} ratio="16 / 10" />    </Grid>  )}const min = 60_000const KINDS = ['weave', 'flow', 'rings', 'aurora', 'drift'] as constconst stripes = (x: number, y: number, t: number) => Math.sin((x + y) * 9 + t) / 2 + 0.5

Colours

ramp takes a tone or your own list of colours, faintest first.

tsx
import { DitherField, Grid } from '@weft-js/warp'export function Ramps() {  return (    <Grid min="sm" cols={3} gap="related">      {TONES.map(ramp => <DitherField key={ramp} ramp={ramp} ratio="16 / 10" />)}    </Grid>  )}const min = 60_000const TONES = ['accent', 'neutral', 'positive', 'caution', 'info', 'highlight'] as const

Pointer

pointer disturbs the field and spark colours the disturbance.

tsx
import { DitherField } from '@weft-js/warp'export function Pointer() {  return (    <DitherField kind="flow" pointer="ripple" spark="highlight" ratio="21 / 9" label="A field that ripples under the pointer" />  )}

Held still

speed={0} holds one frame, and seed chooses which.

tsx
import { DitherField } from '@weft-js/warp'export function Still() {  return (    <DitherField kind="aurora" speed={0} seed={12} ramp="info" ratio="21 / 9" />  )}

When to use

Use it for

  • A hero or section that needs a living background

Reach for something else

  • Dither, when a still picture is enough
  • DitherGlyph, when a word or logo should carry the texture

Playground

Kind
Pattern
Cell4
Pointer
Speed1
import { DitherField } from '@weft-js/warp'<DitherField pointer="ripple" />

Accessibility

  • It moves at the vivid and balanced dials, and holds still at quiet and under reduced motion.
  • It is decorative unless you give it a label.

API Reference

PropTypeDefaultDescription
fillbooleanfalseFills the nearest positioned parent, for a section background.
ratiostring | number—CSS aspect ratio. Defaults to 16 / 9.
labelstring—Names the field (role="img"). Without one it is decorative.
childrenunknown—What it contains.
kind"weave" | Field | "flow" | "rings" | "aurora" | "drift"—The named field, or your own function of (x, y, t).
smoothbooleanfalseYour own kind is smooth: evaluate it on a sparse lattice and interpolate, as the named fields do.
rampRamp—The inks: a tone such as accent, or your own list of colours.
sparkRamp—The colours a disturbed cell takes.
patternPattern—The ordered-dither tile: bayer2, bayer4, bayer8, blue noise or halftone.
cellnumber—CSS pixels per dither cell.
inksnumber—How many inks of a tone ramp to use. Default: the tier's.
speednumber—Multiplies the tier's speed. 0 holds one frame.
gainnumber—Tone gain, around 1. Default: the tier's.
seednumber—Where a held frame sits in the field's time, in seconds.
spreadnumber—How much of the step between inks the pattern may cross, 0–1.
pointerPointerMode | PointerMode[]—How the field answers the pointer: ripple, pull or shockwave, or several.
maskMaskSource—The field shows through this shape.
fadeFade—Dissolves toward left, right, top, bottom, or edges.
revealnumber—Seconds a mask takes to draw itself on, left to right, with a flash where it lands. Needs motion.
fpsnumber—Caps the frame rate while it moves.

RelatedDitherDither glyphCanvas