Image loading & emoji

Takumi fetches the remote images your markup references, accepts images you fetch or decode yourself, and turns emoji into images. Fetch limits, retries, and decode limits come after these, at the end of the page. Caching covers how Takumi keeps downloaded and decoded images between renders.

External imagesCopy Anchor Link

render() and ImageResponse fetch every remote http:// or https:// image the tree draws once its styles apply:

• an <img> src
• background-image, mask-image, and list-style-image, whether style, tw, css, a <style> element, or a ::before rule sets them
• images an animation's @keyframes switch to

An image under display: none is not fetched. A relative URL such as /logo.png is fetched only through your own fetch, which can resolve it.

When user input can reach the markup, set allowUrl, as URLs from user input describes.

To reuse downloaded bytes across renders, pass a fetchCache.

Pre-fetched imagesCopy Anchor Link

Give images a key so the renderer never fetches them. Use the key in any src or CSS url().

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

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

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

data is raw bytes or a function that returns them. Takumi skips fetching any remote URL that already has an entry.

Raw pixelsCopy Anchor Link

Pass raw RGBA pixels instead of encoding a PNG first, and Takumi skips decoding. The Bitmap helper renders a row-major buffer of width * height * 4 bytes as an <img>. This example fills a 64 × 64 image with opaque blue:

import { render } from "takumi-js";
import { Bitmap } from "takumi-js/helpers/jsx";

const pixels = new Uint8Array(64 * 64 * 4);

for (let offset = 0; offset < pixels.length; offset += 4) {
  pixels.set([59, 130, 246, 255], offset);
}

const image = await render(<Bitmap width={64} height={64} data={pixels} />, {
  width: 64,
  height: 64,
});

Set premultiplied when the bytes already have premultiplied alpha. Takumi then uses them as they are. Outside JSX, an image node's src takes the same { width, height, data, premultiplied? } object.

EmojiCopy Anchor Link

takumi-js turns emoji into images by default. It splits each emoji out of the text and fetches its SVG from a CDN, using Twemoji unless you pick another set.

Dynamic fetchingCopy Anchor Link

Set emoji to choose the set. render, renderSvg, renderAnimation, measure, and ImageResponse all take it, and the CDN values match satori's. Each emoji's SVG comes from jsDelivr, at the version the table lists:

¹ See COLR / bitmap fonts to load one.

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

export function GET() {
  return new ImageResponse(<div tw="flex justify-center items-center text-3xl">Hello 👋😁</div>, {
    emoji: "noto", 
  });
}

Emoji detection follows the Unicode presentation rules. A pictograph that defaults to text presentation, such as ‼ or ▶, stays text and renders with your fonts. Add U+FE0F after it to force the emoji image. Add U+FE0E after an emoji to keep the text glyph.

Manual extractionCopy Anchor Link

The extractEmojis helper does the splitting. It replaces each emoji with an image node that points at the CDN. On your own renderer, call it before prepare(), which then fetches the emoji with your other images.

import { extractEmojis } from "takumi-js/helpers/emoji";
import { fromJsx } from "takumi-js/helpers/jsx";
import { Renderer } from "takumi-js/node";

let { node } = await fromJsx(<div tw="flex justify-center items-center text-3xl">Hello 👋😁</div>);
node = extractEmojis(node, "twemoji");

const renderer = new Renderer();
const prepared = await renderer.prepare(node, { width: 1200, height: 630 });

const image = await renderer.render(prepared, { format: "webp" });

COLR / bitmap fontsCopy Anchor Link

Takumi draws emoji from color fonts, either COLR fonts such as Twemoji-COLR or bitmap fonts such as Noto Color Emoji. A COLR file is much smaller than a bitmap font. The glyphs come from the loaded font, so no emoji request goes out.

To use a color font, do both of these:

• Register the font through fonts.
• Set emoji: "from-font".

Variation selectors take priority over font order. A code point followed by U+FE0F renders as a color emoji, even when a text font comes first in the stack. A code point followed by U+FE0E renders as a monochrome glyph, even when a color font comes first. Bare code points follow stack order, as in browsers.

Prepare on your own rendererCopy Anchor Link

A renderer you create yourself fetches nothing on its own. Its prepare() does what render() does before drawing. It styles the source, fetches the images it draws, and loads the font subsets its text uses. Pass the result to the renderer's render, renderSvg, or measure:

const renderer = new Renderer();
const fetchCache = new Map<string, Promise<ArrayBuffer>>();

const prepared = await renderer.prepare(html, {
  width: 1200,
  height: 630,
  images: { fetchCache },
});

const image = await renderer.render(prepared, { format: "webp" });

prepare takes the layout options of render, such as the size, css, lang, and fonts, plus images with the same fetch limits. Rendering the result takes only output options such as format, so the layout stays the one you prepared.

• A prepared source renders on any renderer from the same package, which loads the fonts again if it no longer holds them.
• prepareAnimation prepares every scene of an animation from the options of renderAnimation, which then takes its result.

PdfRenderer from takumi-pdf and Painter from takumi-paint have the same prepare. A PDF's header, footer, and page bands count as part of the document, and rendering a prepared PDF takes the file options such as metadata, outline, and pdfa.

Fetch limitsCopy Anchor Link

import { render } from "takumi-js";

const element = <img src="https://example.com/image.png" />;

const image = await render(element, {
  images: {
    timeout: 3000,
    maxBytes: 4 * 1024 * 1024,
    allowUrl: (url) => new URL(url).hostname === "example.com",
  },
});

images, googleFonts, and fontFromUrl take these options. A custom data loader makes its own requests, so they do not apply to it.

¹ A timeout of 0 or less disables the deadline.

RetriesCopy Anchor Link

GET and HEAD requests make up to three attempts. A request retries when fetch throws a TypeError (such as a connection error) or a TimeoutError, and on HTTP 408, 429, 500, 502, 503, and 504. Takumi waits 100 ms before the first retry and 200 ms before the second. A Retry-After header can extend a wait to at most one second. If it asks for a longer wait, Takumi returns the error without retrying.

Retries also stop when any of these happens:

• the caller's signal aborts
• the deadline passes
• any other HTTP error
• a failure while reading the response body

A custom fetch must honor the abort signal it receives.

Failed fetchesCopy Anchor Link

By default, one image that fails to fetch rejects the whole render. Set throwOnError: false to leave that image out and draw the rest. An emoji with no Twemoji image counts as a failed fetch too.

import { render } from "takumi-js";

const element = <img src="https://example.com/image.png" />;

const image = await render(element, {
  images: {
    throwOnError: false, 
  },
});

URLs from user inputCopy Anchor Link

• allowUrl checks each redirect destination, up to five hops. Each hop shares the same deadline and gets its own attempts.
• A fetchCache hit checks only the requested URL, because cached bytes keep no redirect history. Do not share one fetchCache across different URL policies.
• allowUrl sees URLs, not IP addresses. To filter by resolved address, pass a custom fetch.

Decode limitsCopy Anchor Link

Takumi rejects oversized images when it decodes them. The limits protect servers from decode bombs, which are small files that declare huge dimensions to force huge allocations.

¹ Frames past 1024 are dropped.