Satori

Satori supports a limited subset of HTML elements. It does not support <input>, <style> tags, or external resources via <link> or <script>.

Images

You can use <img> to embed images. It is highly recommended to provide width and height attributes.

For better performance when rendering to other image formats (like PNG), use base64 encoded data, an ArrayBuffer, or a Buffer for the src prop to avoid extra I/O during Satori's execution.

await satori(
  <img src="https://picsum.photos/200/300" width={200} height={300} />,
  options
)

// Using base64 for better performance:
await satori(
  <img src="data:image/png;base64,..." width={200} height={300} />,
  options
)

In environments with limited WASM loading (like Cloudflare Workers), use the satori/standalone build. You must manually load the yoga.wasm binary and initialize Satori using init() before calling satori().

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

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

await init(yogaWasm)

// Now you can use satori as usual
const svg = await satori(...)

To generate an SVG, import satori and call it with a JSX element and an options object. The options object must include width, height, and a fonts array.

Each font object in the fonts array requires:

• name: The font name.
• data: The font data as a Buffer or ArrayBuffer (retrieved via fs in Node.js or fetch in other environments).
• weight: The font weight (e.g., 400).
• style: The font style (e.g., 'normal').

The function returns an SVG string.

import satori from 'satori'

const svg = await satori(
  <div style={{ color: 'black' }}>hello, world</div
  ,
  {
    width: 600,
    height: 400,
    fonts: [
      {
        name: 'Roboto',
        // Use `fs` (Node.js only) or `fetch` to read the font as Buffer/ArrayBuffer and provide `data` here.
        data: robotoArrayBuffer,
        weight: 400,
        style: 'normal',
      },
    ],
  },
)

To use JSX with Satori, you must tell your compiler (like TypeScript or Babel) to use Satori's JSX runtime. You can do this by adding the @jsxImportSource pragma directive at the top of your files containing JSX.

Note: Satori does not support class components; only functional components are supported.

/** @jsxImportSource satori/jsx */

function MyComponent() {
  return <div style={{ color: 'red' }}>Hello Satori</div>;
}

Use the loadAdditionalAsset callback to fetch missing assets (fonts or emojis) on the fly. The callback receives a code (e.g., 'emoji', a language code, or 'unknown') and the segment of text being rendered.

await satori(
  <div>👋 你好</div>,
  {
    loadAdditionalAsset: async (code: string, segment: string) => {
      if (code === 'emoji') {
        return `data:image/svg+xml;base64,...`
      }
      return loadFontFromSystem(code)
    }
  }
)

Satori supports TTF, OTF, and WOFF formats (WOFF2 is not currently supported). You must provide font data as an ArrayBuffer (browser) or Buffer (Node.js).

Multiple fonts can be passed in the fonts array and referenced via fontFamily in your styles.

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

Emojis

Use the graphemeImages option to map specific emojis (graphemes) to image sources. The image will be resized to match the current font size as a square.

Locales

Specify the language via the lang attribute on elements to ensure correct rendering for specific locales.

await satori(
  <div style={{ fontFamily: 'Inter' }}>Next.js is 🤯!</div>,
  {
    graphemeImages: {
      '🤯': 'https://cdnjs.cloudflare.com/ajax/libs/twemoji/14.0.2/svg/1f92f.svg',
    },
  }
)

// Using lang attribute for locales:
await satori(
  <div lang="ja-JP">骨</div>
)

Font Embedding

By default, Satori renders text as <path> elements in the SVG to embed font data directly. To use standard <text> elements instead, set embedFont: false.

Pixel Grid Rounding

Use pointScaleFactor to control how layout values are rounded to the pixel grid. This improves rendering precision on high-DPI displays.

Debugging

Pass debug: true to draw bounding boxes around elements for layout debugging.

const svg = await satori(
  <div style={{ color: 'black' }}>hello, world</div>,
  {
    embedFont: false,
    pointScaleFactor: 2,
    debug: true,
  },
)

When loading fonts into Satori via the FontLoader, you must provide an array of FontOptions objects. Each object specifies the raw font data and its metadata to ensure correct rendering and fallback behavior.

Key properties:

• data: The raw font file as a Buffer or ArrayBuffer.
• name: The font family name (e.g., 'sans-serif').
• weight: The numeric weight (e.g., 400, 700) or a WeightName ('normal', 'bold').
• style: The font style ('normal' or 'italic').
• lang: An optional locale string (e.g., 'ja') to associate the font with a specific language. If not set, it defaults to an internal unknown suffix.

const fontOptions: FontOptions[] = [
  {
    name: 'Inter',
    data: fontBuffer,
    weight: 400,
    style: 'normal'
  },
  {
    name: 'Inter',
    data: boldFontBuffer,
    weight: 700,
    style: 'normal'
  }
];