Satori

Images

Use <img> and set width and height explicitly so layout is stable:

<img src="https://picsum.photos/200/300" width={200} height={300} />

With backgroundImage: url(...), the image stretches to fit the element unless you set backgroundSize. When the SVG will be rasterized to PNG afterward, prefer a base64 data URI (or a Buffer/ArrayBuffer) as src so Satori does not perform extra network I/O.

Only PNG, JPEG, and GIF decode reliably. AVIF and WebP do not work and silently fail to render. Convert them to PNG or JPEG before passing them in (for example with sharp), and remember that a modern URL ending in .jpg may still serve WebP via content negotiation, so convert the bytes rather than trusting the extension.

Do not put an alt attribute on <img>. Satori treats it as text content, so the value can leak into the render as visible words drawn on the canvas. Leave it off; the output is a static image and gains nothing from it.

Fonts

Any rendered text requires at least one font. Satori accepts TTF, OTF, and WOFF. WOFF2 is not supported. Pass font data as ArrayBuffer (web) or Buffer (Node.js):

await satori(<div style={{ fontFamily: 'Inter', display: 'flex' }}>Hello</div>, {
  width: 600,
  height: 400,
  fonts: [
    { name: 'Inter', data: inter, weight: 400, style: 'normal' },
    { name: 'Inter', data: interBold, weight: 700, style: 'normal' },
  ],
})

Pass multiple fonts and reference any of them via fontFamily. Define fonts once and reuse the object across renders for better performance rather than rebuilding it per call.

Advanced typography (kerning, ligatures, other OpenType features) is not supported, and RTL languages are not supported.

Emoji

Text glyphs render from the provided fonts; emoji do not come for free. Map specific graphemes to image sources with graphemeImages, where each image is sized to the current font size as a square:

await satori(<div style={{ display: 'flex' }}>Ship it 🚀</div>, {
  ...,
  graphemeImages: { '🚀': 'https://cdnjs.cloudflare.com/.../1f680.svg' },
})

Locales

The same characters can render differently per locale. Set lang on an element to force a locale, for example <div lang="ja-JP">骨</div>.

Dynamically loading fonts and emoji

When a text segment needs a font or emoji image that was not provided up front, Satori calls loadAdditionalAsset(code, segment). code is the detected language code, or 'emoji', or 'unknown'. Return a data URI for emoji, or font data for text:

loadAdditionalAsset: async (code, segment) => {
  if (code === 'emoji') return `data:image/svg+xml;base64,...`
  return loadFontFromSystem(code)
}

Output and rendering options

• embedFont (default true): text is emitted as <path> with the glyph outlines inlined, so downstream tools need no font files. Set embedFont: false to emit <text> instead (smaller output, but the renderer must have the font).
• pointScaleFactor: passed through to Yoga to control how layout values round to the pixel grid; raise it for crisper output on high-DPI targets.
• debug: true: draws bounding boxes, which is the fastest way to see why layout is off.

Runtime support

Satori runs in the browser, Node.js (>= 16), and Web Workers. It bundles its WASM (Yoga) dependency as base64 and loads it at runtime. In environments that forbid dynamic WASM loading, use the standalone build and initialize Yoga yourself:

import satori, { init } from 'satori/standalone'

const res = await fetch('https://unpkg.com/satori/yoga.wasm')
await init(await res.arrayBuffer())
const svg = await satori(...)

Debugging workflow

When output looks wrong, work through these in order, since they cover the overwhelming majority of cases:

1. Did every multi-child container get display: 'flex'? Missing display is the most common error and silent misalignment.
2. Is the direction right? Remember the default is row. Vertical stacks need flexDirection: 'column'.
3. Did a shorthand value lose its unit? Expected length unit means a padding/margin/border value needs px or %.
4. Is the property actually supported? Check references/css-support.md. Unsupported properties are ignored or throw rather than approximated.
5. Are you relying on z-index, calc, or currentColor off the color property? None of those work; reorder markup, precompute, or set explicit values.
6. Turn on debug: true to see bounding boxes and confirm the layout tree.

Reference files

• references/css-support.md — the complete supported-CSS matrix with allowed values and defaults, plus the global limitation notes. Read it whenever you are unsure if a property or value is supported.