Skip to content
kerfjsGitHub

Dither

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

SourcePackage @kerf-js/veneerTry it

Preview

tsx
import { Dither } from '@kerf-js/veneer'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 @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
Cell4
Codeupdates as you change the controls
import { Dither } from '@kerf-js/veneer'<Dither />

Usage

tsx
import { Dither } from '@kerf-js/veneer'<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 '@kerf-js/veneer'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 '@kerf-js/veneer'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 '@kerf-js/veneer'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 SOFT = { angle: 30 }const ALGORITHMS = [  'bayer2',  'bayer8',  'blue',  'halftone',  'floyd',  'atkinson',] as const

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 '@kerf-js/veneer'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

Accessibility

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

API Reference

PropTypeDefaultDescription
srcstring—An image to dither. The real <img> stays underneath, for alt text, for no script and for a cross-origin failure.
altstring—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.
gradientGradient—With no src: { angle, radial, from, to }.
algorithmAlgorithm—atkinson by default for images, bayer8 for gradients.
rampRamp—The inks: a tone such as accent, or your own list of colours.
cellnumber—CSS pixels per dither cell. Larger cells give a coarser, chunkier picture.
inksnumber—How many inks of the ramp to use. Default: the tier's.
contrastnumber—Tone contrast, around 1.
invertbooleanfalseSwaps light and dark.
fillbooleanfalseFills the nearest positioned parent instead of keeping a ratio, for a section background.
ratiostring | number—Width to height.
labelstring—Its accessible name. Fields show it; icon-only controls speak it.

RelatedDither fieldDither glyph