Images & SVG

Images get into Takumi through three paths: a URL the renderer fetches, a data URL embedded in the JSX, or raw bytes you load yourself. Pick based on where the source lives and how often you need it.

Image sources

// 1. URL — renderer fetches before rendering.
<img src="https://example.com/avatar.png" width={64} height={64} />;

// 2. Data URL — bytes inline in the JSX, no network call.
<img src="data:image/png;base64,iVBORw0KGgo..." width={64} height={64} />;

// 3. Persistent store key — see "Persistent image store" below.
<img src="my-logo" width={64} height={64} />;

Background images work the same way:

<div style={{ backgroundImage: "url(https://example.com/hero.jpg)" }} />

Fetching strategies

For one-off renders the default behavior — Takumi fetches every src it sees — is fine. For production workloads you want to control when and how fetches happen.

Inline cache

Pass a Map to resourcesOptions.cache and the renderer will check it before fetching. Cheapest way to avoid re-decoding the same URL across requests.

import { render } from "takumi-js";

const cache = new Map<string, ArrayBuffer>();

const image = await render(<img src="https://example.com/image.png" />, {
  resourcesOptions: { cache },
});

Extract, fetch, render

For multi-image scenes you can walk the node tree once, fetch every URL in parallel, and hand the byte map to the renderer.

import { Renderer } from "takumi-js/node";
import { fromJsx } from "takumi-js/helpers/jsx";
import { extractResourceUrls, fetchResources } from "takumi-js/helpers";

const renderer = new Renderer();
const { node, stylesheets } = await fromJsx(<Gallery />);

const urls = extractResourceUrls(node);
const fetchedResources = await fetchResources(urls);

const image = await renderer.render(node, { stylesheets, fetchedResources });

function Gallery() {
  return <div />;
}

This is the path to take when you want to add retries, parallelism limits, or a CDN in front of the fetch.

Persistent store

For assets that appear on every render — logos, backgrounds, brand fonts — preload them once and reference by a stable key. See Persistent image store below.

SVG

SVG is supported through resvg. It rasterizes at render time, at the node's display size, so the output is sharp at any scale.

Inline SVG works as a JSX child:

<svg width="64" height="64" viewBox="0 0 24 24">
  <circle cx="12" cy="12" r="10" fill="#6366f1" />
</svg>

External SVG works through <img>:

<img src="https://example.com/logo.svg" width={120} height={32} />

Supported subset: shapes, paths, transforms, gradients, masks, basic filters, embedded raster images, text using fonts the renderer already knows about. CSS animations and JS handlers are ignored — Takumi rasterizes a static frame.

For SVG with text, register the font with the renderer (not inside the SVG with @font-face) so glyphs resolve through the same fallback chain as the rest of the scene.

object-fit and image-rendering

object-fit controls how an image fills its box when the box's aspect ratio differs from the image's.

<img src="/hero.jpg" width={1200} height={400} style={{ objectFit: "cover" }} />

image-rendering controls the resampling algorithm.

Persistent image store

Assets that show up in every render shouldn't be re-fetched and re-decoded every time. The persistent image store keeps decoded buffers alive on the renderer; you reference them by a string key.

import { ImageResponse } from "takumi-js/response";

export function GET() {
  return new ImageResponse(<OgImage />, {
    persistentImages: [
      { src: "my-logo", data: () => fetch("/logo.png").then((res) => res.arrayBuffer()) },
      { src: "background", data: () => fetch("/background.jpg").then((res) => res.arrayBuffer()) },
    ],
  });
}

function OgImage() {
  return (
    <div style={{ backgroundImage: "url(background)" }}>
      <img src="my-logo" />
    </div>
  );
}

The same key works in src attributes and any background-image, mask-image CSS property.

For long-running servers, build the renderer once and call putPersistentImage directly:

const renderer = new Renderer({ fonts: [...] });
await renderer.putPersistentImage("my-logo", await fetch("/logo.png").then(r => r.arrayBuffer()));