satori

name

satori

description

Expert guidance for Satori, the library that converts JSX/HTML and CSS into SVG (the engine behind dynamic Open Graph images and social cards). Use whenever writing or debugging Satori markup e.g. authoring JSX for OG images, choosing CSS that Satori actually supports, fixing layout that renders wrong, embedding fonts, rendering emoji or images, or resolving Satori errors like "Expected length unit" or unsupported property issues. Reach for this any time someone renders HTML/CSS to SVG or PNG with Satori, even if they do not name it.

Satori

Satori converts JSX-like HTML and CSS into SVG. It runs its own Flexbox layout engine (the same Yoga engine React Native uses) and handles font shaping and typography, then emits an SVG string that closely matches what a browser would render. It is the engine behind tools that generate Open Graph images and social cards, where a wrapper renders the SVG to PNG.

Treat yourself as an expert in Satori. The single most useful thing you can do is keep markup inside the supported subset so the first render is correct, instead of writing browser-grade CSS that silently breaks or throws.

Basic usage

import satori from 'satori'

const svg = await satori(
  <div style={{ color: 'black', display: 'flex' }}>hello, world</div>,
  {
    width: 600,
    height: 400,
    fonts: [
      { name: 'Roboto', data: robotoArrayBuffer, weight: 400, style: 'normal' },
    ],
  },
)

satori(...) returns an SVG string. width and height set the canvas. At least one font is required whenever any text is rendered (see Fonts).

Constraints

These behaviors most often produce wrong output or runtime errors. Account for them before writing markup.

• Every element that contains more than one child must declare display: 'flex' (or display: 'none'). Satori is Flexbox only. A div with multiple children and no explicit display will throw. Default to putting display: 'flex' on every container. Single text children are tolerated, but being explicit is safest.
• Default flexDirection is row, not column. This is the opposite of how people mentally stack divs. Set flexDirection: 'column' whenever you want vertical stacking.
• Padding and margin shorthand need explicit units on every value. padding: '0 36' throws Expected length unit. Write padding: '0px 36px', and '0px 36px 36px 36px' for the four value form. A single bare number like padding: 36 is fine, because Satori treats a lone number as px.
• Use flex layout for everything, including overlap. For overlapping or precisely placed elements, use position: 'absolute' with top/left/right/bottom on a position: 'relative' parent.
• Never put HTML entity references in text. Satori does not decode them, so publish‑ready renders the literal characters ‑ on the image instead of a non-breaking hyphen. This applies to numeric (‑,  ) and named ( , &, —) entities alike. Write the actual Unicode character directly in the string instead — publish‑ready (or the literal glyph publish‑ready) for a non-breaking hyphen,   for a non-breaking space, & for an ampersand, — for an em dash.

CSS support

Satori implements a subset of CSS. Assume anything not in the supported table is unsupported, and verify before relying on it. For the complete matrix with allowed values and defaults, read references/css-support.md.

Supported

Category	Properties
Layout	display (flex, contents, none), position (relative, static, absolute), top/right/bottom/left, width/height, min/max width/height, overflow (visible, hidden)
Flex	flexDirection, flexWrap, flexGrow, flexShrink, flexBasis, alignItems, alignContent, alignSelf, justifyContent, gap
Box	margin, padding, border (width, solid/dashed style, color, shorthand), borderRadius, boxSizing, boxShadow, opacity
Color and background	color, backgroundColor (single value), backgroundImage (linear-gradient, repeating-linear-gradient, radial-gradient, repeating-radial-gradient, url), backgroundPosition, backgroundSize (cover, contain, auto, two-value), backgroundClip (border-box, text), backgroundRepeat
Text	fontFamily, fontSize, fontWeight, fontStyle, textAlign, textTransform, textOverflow (clip, ellipsis), textDecoration, textShadow, lineHeight, letterSpacing, whiteSpace, wordBreak, textWrap (wrap, balance), textIndent, tabSize, lineClamp
Transform and effects	transform (translate, rotate, scale, skew), transformOrigin, filter, clipPath, mask (maskImage, maskPosition, maskSize, maskRepeat), objectFit, objectPosition, WebkitTextStroke
Variables	--name declarations and var(--name, fallback) usage, including inheritance and nesting

Unsupported

Property or feature	Notes and workaround
z-index	No stacking contexts. Elements paint in document order, so later siblings render on top. Reorder markup to control layering.
calc()	Precompute values in JavaScript before they reach the style object.
currentColor outside color	Resolves only for the color property. Set explicit values for borders, backgrounds, and fills.
3D transforms	Not supported. Use 2D translate, rotate, scale, and skew only.
min-content, max-content, fit-content	Not supported for min/max width and height.
flexBasis: auto	Not supported. Use an explicit basis or rely on width/height.
Interactive or resource elements	No <input>, <style>, <script>, or <link>. Only static, visible elements render.
<img> alt, SVG <title>	Render as visible text on the image. Omit alt; strip <title> from inline SVG (see Images and Inline SVG).
WOFF2 fonts	Convert to TTF, OTF, or WOFF (see Fonts).
AVIF / WebP images	Convert to PNG or JPEG (see Images).
Kerning, ligatures, OpenType features	Advanced typography is not supported.
RTL languages	Not supported.

HTML elements

Satori supports only static, visible elements. Interactive or resource-loading elements are out: no <input>, no <style>, no <script>, no <link>. The output is not guaranteed to match a browser pixel for pixel, because Satori runs its own SVG 1.1 based layout engine. Stick to <div>, <span>, <img>, <svg>, and text.

Inline SVG

Inline <svg> works and is the reliable way to place vector logos and icons. Keep the markup well formed: include a viewBox, and use explicit width/height. Grouping (<g transform=...>), fill-rule, and paths without fills render correctly.

Strip any <title> element from the SVG markup before passing it in. Satori treats it as text content, so the title can leak into the render as visible words drawn on the image. Logos pulled from icon libraries often ship with one, so check and remove it.

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.