Output Formats

render() returns encoded image bytes. The format option picks the encoder; the rest of this page covers the knobs each one exposes, the pixel-density control, and the separate vector-SVG path.

Picking a format

format is part of a discriminated union, so the format-specific options only appear on the formats that accept them. quality cannot pair with PNG, and lossless is WebP-only.

import { render } from "takumi-js";

await render(<OgImage />, { width: 1200, height: 630, format: "png" });
await render(<OgImage />, { width: 1200, height: 630, format: "jpeg", quality: 80 });
await render(<OgImage />, { width: 1200, height: 630, format: "webp", lossless: true });

Format	Alpha	Notes
`png` (default)	Yes	Lossless. Use when you need transparency or exact pixels.
`jpeg`	No	Lossy; `quality` 0–100. Alpha is flattened. Smallest files for photographic content.
`webp`	Yes	Lossy with `quality`, or `lossless: true`. Omitting both encodes losslessly.
`ico`	Yes	Favicon container, PNG-encoded inside.
`raw`	Yes	Uncompressed RGBA bytes, `width × height × 4`. For video pipelines and custom encoders.

quality only applies to jpeg and lossy webp. For WebP, lossless wins over quality.

On @takumi-rs/wasm, WebP is always lossless — lossy WebP encoding is native-only. The quality and lossless knobs are absent from the WASM types.

Raw frames

format: "raw" skips encoding and hands back the RGBA buffer directly. Feed it to ffmpeg or any encoder you already run. The keyframe animation page streams raw frames into ffmpeg for video output.

devicePixelRatio scales the output resolution without touching the layout. A 1200 × 630 render at devicePixelRatio: 2 produces a 2400 × 1260 image whose elements keep their CSS sizes — the same trick a retina screen uses.

await render(<OgImage />, { width: 1200, height: 630, devicePixelRatio: 2 });

Dithering

dithering trades a little noise for smoother gradients when colors are quantized during encoding, removing visible banding.

none (default)
ordered-bayer
floyd-steinberg

await render(<Gradient />, { width: 1200, height: 630, dithering: "floyd-steinberg" });

Animated output

renderAnimation() encodes a sequence as WebP, APNG, or GIF. See Keyframe Animation.

Vector SVG

renderSvg() is the second output backend. It takes the same input and resource pipeline as render(), but returns an <svg> document string instead of a raster bitmap — real <rect>, <path>, gradients, glyph outlines, and embedded images, drawn from the same layout. If you came from satori for its SVG output, this is the direct equivalent.

import { render, renderSvg } from "takumi-js";

const png = await render(<OgImage />, { width: 1200, height: 630 });
const svg = await renderSvg(<OgImage />, { width: 1200, height: 630 });

Because SVG is a vector format, the raster-only knobs — format, quality, lossless, dithering, drawDebugBorder, devicePixelRatio — do not apply.

Cancellation

Every render takes an optional AbortSignal. Pass signal to abort a render that is still fetching fonts or images; an already-aborted signal throws before any work starts.

await render(<OgImage />, { width: 1200, height: 630, signal: request.signal });