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, caches, and decode limits come after these, at the end of the page.

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.

Share a fetchCache across renders to reuse downloaded bytes and pending requests:

import { render } from "takumi-js";

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

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

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

fetchCache takes a Map<string, Promise<ArrayBuffer>> or any object with the same get, set, and delete methods. Values are promises, not raw buffers.

Emoji images from the emoji option are cached across renders without a fetchCache, up to 8 MB per fetch function.

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:

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.

On your own renderer, prepare() splits emoji and fetches their images the same way.

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, emoji included, 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,
  emoji: "twemoji",
  images: { fetchCache },
});

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

• prepare takes the layout options of render, such as the size, css, lang, emoji, and fonts, plus images with the same fetch limits. Rendering a prepared source takes only the output options, so the layout cannot change between the two calls.
• With your own fetch, a relative URL such as /logo.png reaches it, so it can resolve the path and apply its own checks. Without one, only http:// and https:// URLs are fetched.
• A prepared source renders on any renderer from the same package. A renderer that no longer holds its fonts loads them again.

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",
  },
});

... (+124 lines) [see remaining: rtk proxy git show feat/render-needs-bindings:docs/content/docs/images.mdx | tail -n +188]