| name | takumi-usage |
| description | Guidelines, syntax, templates, API usage, and styling best practices for rendering static/animated images and vector SVG using Takumi. |
Takumi Usage & Best Practices
All-in-one guide for rendering with Takumi. Built-in layout rules, advanced styles, and performance.
JS / TS API Reference
1. Static Render (render & renderSvg)
Renders JSX templates, HTML strings, or JSON node trees to raster buffers (PNG/JPEG/WebP) or vector SVG markup.
import { render, renderSvg } from "takumi-js";
const pngBuffer = await render(
<div tw="w-full h-full bg-zinc-950 flex items-center justify-center">
<h1 tw="text-white text-6xl">Takumi Engine</h1>
</div>,
{
width: 1200,
height: 630,
format: "png",
quality: 90
}
);
const svgString = await renderSvg(
<div tw="w-full h-full bg-zinc-900">
<span tw="text-white">Scalable Vector</span>
</div>,
{ width: 800, height: 400 }
);
2. Animated Render (renderAnimation)
Compiles sequences of scenes into animated WebP, GIF, or APNG buffers.
import { renderAnimation } from "takumi-js";
const animatedBuffer = await renderAnimation({
width: 400,
height: 400,
fps: 30,
format: "webp",
quality: 80,
scenes: [
{
durationMs: 1500,
node: (
<div tw="w-full h-full bg-black flex items-center justify-center">
<div tw="w-24 h-24 bg-rose-500 animate-bounce rounded-full" />
</div>
)
}
]
});
3. Edge / Framework Integration (ImageResponse)
A next/og compatible handler designed for Edge runtimes, Cloudflare Workers, Next.js API endpoints, and standard HTTP server frameworks.
import { ImageResponse } from "takumi-js/response";
export function GET() {
return new ImageResponse(
<div tw="w-full h-full bg-slate-900 flex items-center justify-center">
<h1 tw="text-white text-5xl">Dynamic OG Card</h1>
</div>,
{
width: 1200,
height: 630
}
);
}
4. Parsing Helpers (takumi-js/helpers/*)
Low-level utilities for compiling layout elements without executing the full renderer.
import { fromHtml } from "takumi-js/helpers/html";
import { fromJsx } from "takumi-js/helpers/jsx";
const htmlNodeTree = fromHtml(
"<div class='flex'><span>Hello</span></div>",
{ max_depth: 512 }
);
const jsxNodeTree = fromJsx(
<div tw="flex"><span>Hello</span></div>
);
Options Configuration (RenderOptions)
fonts: An array of custom fonts [{ name, url, weight, style }]. Values can point to remote URLs (WOFF2/WOFF/TTF), local file paths, or binary Node.js Buffer arrays.emoji: Configures the emoji fallback strategy: "twemoji" (default), "blob-emoji", "openmoji", "noto-emoji", or "from-font" (uses custom loaded font glyphs).images: Option to pass pre-fetched image arrays [{ url, buffer }] or supply a shared caching fetch-client configuration.stylesheets: An array of raw global CSS string sheets to inject into the rendering layout context.
Hidden Layout Capabilities (Deep-Dive)
1. Auto-scaling Text (text-fit)
Automatically scales font-size to fit the containing inline line-box width, avoiding clipping or wrapping.
- Syntax:
text-fit: [ none | grow | shrink ] [ consistent | per-line | per-line-all ]? [percentage]?
- Example:
tw="text-fit-grow-consistent" or style={{ textFit: "grow consistent 120%" }}.
2. CSS Motion Paths (offset-path)
Enables complex placement and animation sequences of elements along custom vector paths or geometric rays.
- Properties:
offset-path, offset-distance (percentage), offset-rotate (angle / auto).
- Syntax:
ray(<angle> <size> contain? at <position>?) or path("<svg path command>") or basic shapes (circle(), polygon(), inset()).
3. OpenType Typography Settings
Provides fine-grained control over font rendering features and variable layout configurations.
font-variation-settings: Configures variable font axis settings (e.g. "'wght' 750, 'wdth' 90").font-feature-settings: Enables OpenType font ligatures, kerning, and variants (e.g. "'ss01' 1, 'kern' 1").
4. Custom Filters & Graphics
filter: Supports blur(), brightness(), contrast(), drop-shadow(), grayscale(), hue-rotate(), invert(), opacity(), saturate(), sepia().mix-blend-mode & background-blend-mode: Layer blending modes (e.g. multiply, screen, overlay).backdrop-filter: Applies filter effects to elements behind the container.clip-path: Clips elements via shapes: polygon(...), circle(...), inset(...).
5. Layout Defaults
- CSS Grid support: Supports
grid-cols-X, gap-X, flex, and block layout.
- Tag Presets: Custom HTML styles are pre-mapped for tags:
h1–h6, div, pre (keeps space layout), strong, em, blockquote, and hr.
- Line Breaks:
<br> tags parse to \n in text elements automatically.
Rust Crate API (takumi)
use takumi::prelude::*;
use takumi::render;
let node = Node::container([Node::text("Hello, world!").with_style(
Style::default().with(StyleDeclaration::font_size(Length::Px(32.0).into())),
)]);
let mut fonts = Fonts::default();
fonts.register(FontResource::new(include_bytes!(
"../../assets/fonts/geist/Geist[wght].woff2"
)))?;
let options = RenderOptions::builder()
.viewport(Viewport::new((1200, 630)))
.node(node)
.fonts(&fonts)
.build();
let image = render(options)?;
To build the node tree from HTML instead, enable the from-html feature and use from_html:
use takumi::prelude::*;
use takumi::{from_html, render};
let mut fonts = Fonts::default();
fonts.register(FontResource::new(include_bytes!(
"../../assets/fonts/geist/Geist[wght].woff2"
)))?;
let html = r#"<div style="background: red; width: 100%; height: 100%;"></div>"#;
let node = from_html(html, FromHtmlOptions::default())?;
let options = RenderOptions::builder()
.viewport(Viewport::new((1200, 630)))
.node(node)
.fonts(&fonts)
.build();
let image = render(options)?;
