Astro Image Service

Sweetcorn provides an Astro integration that adds a custom image service to generate dithered images. With the integration installed, you can easily apply dithering to any image that uses Astro’s <Image> and <Picture> components.

Prerequisites

You will need to have an Astro website set up. If you don’t have one yet, you can follow the “Install Astro” guide in the Astro docs to create one.

Quick start

1. Install the Astro integration by running the following command in your terminal:

   npm

   npx astro add @sweetcorn/astro

   pnpm

   pnpm astro add @sweetcorn/astro

   yarn

   yarn astro add @sweetcorn/astro

2. Apply dithering to your images using the dither prop:

   ---
   import { Image } from 'astro:assets';
   import exampleImage from './example.jpg';
   ---
   
   <Image dither="bayer-8" src={exampleImage} alt="Example" />

   See the “Algorithms” page for examples of all algorithms supported in the dither prop.

3. Start the development server to see the integration in action.

Usage

<Image> and <Picture>

When using Astro’s <Image> and <Picture> components, set the dither prop to one of the supported algorithms to apply dithering to the image:

---
import { Image, Picture } from 'astro:assets';
import example from './example.jpg';
---

<Image dither="atkinson" src={example} alt="Example" />

<Picture dither="stucki" src={example} alt="Example" />

getImage()

When generating images programmatically with Astro’s getImage() API, set dither to one of the supported algorithms in the options object:

import { getImage } from 'astro:assets';
import example from './example.png';

const ditheredImage = await getImage({
  src: example,
  dither: 'blue-noise',
});

Styling dithered images

When using <Image> or <Picture>, dithered images are given classes to help target them in CSS.

You can target all dithered images using the sw-dithered class in your CSS:

.sw-dithered {
  /* Styles for all dithered images */
}

You can also target images dithered with a specific algorithm using the algorithm name, prefixed with sw-.

For example, to target images dithered with the Atkinson or Floyd-Steinberg error diffusion algorithms:

.sw-atkinson,
.sw-floyd-steinberg {
  /* Styles for images dithered with these algorithms */
}

Configuration

The Sweetcorn integration can be configured by passing options in your Astro config file:

astro.config.mjs

import { defineConfig } from 'astro/config';
import sweetcorn from '@sweetcorn/astro';

export default defineConfig({
  integrations: [
    sweetcorn({
      // Configuration options here
    }),
  ],
});

The Sweetcorn integration supports the following configuration options.

defaultDitherAlgorithm

Type: "atkinson" | "bayer-16" | "bayer-2" | "bayer-4" | "bayer-8" | "blue-noise" | "burkes" | "dot-4" | "dot-6" | "dot-8" | "dot-diagonal-10" | "dot-diagonal-16" | "dot-diagonal-6" | "dot-diagonal-8" | "dot-horizontal-3x5" | "dot-horizontal-6" | "dot-vertical-5x3" | "dot-vertical-6" | "false-floyd-steinberg" | "floyd-steinberg" | "jarvis-judice-ninke" | "pigeon" | "sierra" | "sierra-lite" | "sierra-two-row" | "simple-diffusion" | "stucki" | "threshold" | "white-noise"

By default, no dithering algorithm is applied to images unless a dither option is passed to the <Image> component or getImage() call.

If you want to apply a dithering algorithm to images by default, you can set the defaultDitherAlgorithm to your preferred algorithm. This algorithm will be used whenever no specific dither option is provided.

sweetcorn({
  defaultDitherAlgorithm: 'atkinson',
}),

When using a default algorithm, you can opt out of dithering by setting dither to false in the <Image> component or getImage().

customThresholdMaps

Type: Record<string, number[][]>

You can provide your own custom threshold maps for dithering by passing them to the customThresholdMaps option.

Each map should be a two-dimensional array of numbers representing the threshold values as 8-bit integers (0–255). All rows must be of the same length.

sweetcorn({
  customThresholdMaps: {
    'custom-2x2-map': [
      [0, 128],
      [192, 64],
    ],
  },
}),

You can then use your custom threshold maps using the dither prop:

<Image src={myImage} dither="custom-2x2-map" />

See “Threshold map dithering” for more details.

customDiffusionKernels

Type: Record<string, number[][]>

You can provide your own custom error diffusion kernels for dithering by passing them to the customDiffusionKernels option.

Each kernel should be a two-dimensional array of numbers representing the diffusion weights. All rows must be of the same length.

sweetcorn({
  customDiffusionKernels: {
    // Implements the Floyd-Steinberg kernel:
    'custom-kernel': [
      [0,    0,    7/16],
      [3/16, 5/16, 1/16],
    ],
  },
}),

You can then use your custom diffusion kernels using the dither prop:

<Image src={myImage} dither="custom-kernel" />

See “Error diffusion dithering” for more details.

Types

DitheringAlgorithm type

import type { DitheringAlgorithm } from '@sweetcorn/astro';

The DitheringAlgorithm type represents all valid algorithms that can be passed to the dither prop in Astro’s image APIs. It can be helpful when typing a component that accepts a dither algorithm as a prop:

src/components/DitheredFigure.astro

---
import type { DitheringAlgorithm } from '@sweetcorn/astro';
import type { ImageMetadata } from 'astro';
import { Image } from 'astro:assets';

interface Props {
  algorithm: DitheringAlgorithm;
  image: ImageMetadata;
}

const { algorithm, image } = Astro.props;
---

<figure>
  <Image src={image} alt="" dither={algorithm} />
  <figcaption><slot /></figcaption>
</figure>