Skip to content
kerfjsGitHub

DitherField

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

SourcePackage @kerf-js/veneerTry it

Preview

tsx
import {  Button,  DitherField,  Heading,  Inset,  Stack,  Text} from '@kerf-js/veneer'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. kerf builds, tests and ships it.        </Text>        <Button icon="rocket">Start a project</Button>      </Stack>    </Inset>  </DitherField>  )}

Installation

npm install @kerf-js/veneer

Try it

Change the controls: the preview and its code update together. The address keeps what you set, so you can link to it.

Live preview
Controls
Kind
Pattern
Cell4
Pointer
Speed1
Codeupdates as you change the controls
import { DitherField } from '@kerf-js/veneer'<DitherField pointer="ripple" />

Usage

tsx
import { DitherField } from '@kerf-js/veneer'

Kinds

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

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

Pointer

pointer disturbs the field and spark colours the disturbance.

tsx
import { DitherField } from '@kerf-js/veneer'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 '@kerf-js/veneer'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

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.
kindFieldName | Field—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