Writing an island
Mount an interactive component over a drawing a Typst function writes, a render island, with the Typst drawing as its fallback for print, PDF and renderers without it.
A render island is an interactive component that typstream mounts where a document's Typst marks one. The marker
wraps the island's fallback, a drawing in plain Typst: what prints, what exportPdf() and standalone HTML contain,
what shows while the component's code loads, and what every renderer without the component shows. Islands are for
teachers and students alike: an interactive mind map in a lesson, a simulation in a handout.
@typstream/mindmap is one; this guide builds another.
An island has four parts:
- A Typst function that draws the fallback and writes the marker around it, with the data the component needs.
- The plugin that mounts that function and declares the island's name (
islands), with aparsethat checks the data. - A component for the name: a React component for
<Typstream islands>, or a framework-free renderer formountTypstream. - The app pairs them:
plugins={[plugin]}andislands={{ name: Component }}. A marker becomes an island only when a loaded plugin declares its name and a component is given for it; otherwise the fallback stays.
The marker
The marker is the island contract. In the HTML target it is a typstream-island element around the fallback, with
the island's name and its data as JSON. In the paged target it is a metadata labelled <typstream-island> at the
top left of the island's block, whose value has the name, the data and the block's size; the engine finds it in the
laid-out document and sends its page and position with every paged artifact. Copy this function:
/// Wraps `fallback` in an island marker named `name`, carrying `data` (JSON-encodable). `source` is content the
/// document wrote (the island function's argument), which locates the island in it.
#let _island(name, data, fallback, source: none) = context if target() == "html" {
html.elem("typstream-island", attrs: (name: name, props: json.encode(data, pretty: false)), html.frame(fallback))
} else {
layout(size => {
let height = measure(fallback, width: size.width).height
block(breakable: false, width: 100%, {
let value = (name: name, data: data, width: size.width / 1pt, height: height / 1pt, source: source)
[#metadata(value)<typstream-island>]
fallback
})
})
}- The island covers its marker: the fallback's box in the HTML target, the full-width block in the paged one. Draw a fallback the size you want the component to have.
datamust survivejson.encode: strings, numbers, booleans, arrays and dictionaries. Resolve everything the component needs (colours, sizes) in Typst, so the two agree.sourceis how the engine knows where the island is in the document, which decidesisIncompletein the paged target: pass the content the document gave your function.- Follow edu's rule for streaming: every parameter has a default and accepts what a stream cut leaves (
(2is the number 2,"#16an unfinished colour). Draw what has arrived; write no marker for nothing.
Here is a counter, #counter(start: 3)[Push-ups]: a box with a label and a number, and a component with a button.
// lib.typ of @acme/counter:0.1.0
#import "island.typ": _island
/// A number readers can count up from.
#let counter(start: 0, ..label) = {
let start = if type(start) == int { start } else { 0 }
let label = label.pos().join()
_island("counter", (start: start), box(stroke: 1pt, inset: 8pt)[#label: #start], source: label)
}The plugin
import { definePlugin, type IslandSpec } from "@typstream/core";
interface CounterData {
start: number;
}
export const counterIsland: IslandSpec<CounterData> = {
description: "A number readers can count up from.",
// The data is untrusted: the document wrote it. Return undefined to keep the fallback.
parse: (data) => {
const start = (data as { start?: unknown } | null)?.start;
return typeof start === "number" && Number.isSafeInteger(start) ? { start } : undefined;
},
};
export const counter = definePlugin({
key: "acme/counter",
engine: { files: FILES, preamble: '#import "@acme/counter:0.1.0": counter\n' },
prompt: { catalogue: CATALOGUE, rules: ["Use `#counter(start: n)` when the reader should count."] },
islands: { counter: counterIsland as IslandSpec },
});IslandSpec and the island types are beta.
The component
React
A component gets IslandProps: the parsed data, isIncomplete, the target it shows in, its index among the
document's islands of its name, and file(path), the bytes of a file the document has (its own, and the images its
resolveImage resolved).
import type { IslandProps } from "@typstream/core";
import { useState } from "react";
export function Counter({ data, isIncomplete }: IslandProps<CounterData>) {
const [count, setCount] = useState(data.start);
return (
<div className="acme-counter">
<button type="button" disabled={isIncomplete} onClick={() => setCount((c) => c + 1)}>
Count: {count}
</button>
</div>
);
}<Typstream source={text} plugins={[counter]} islands={{ counter: Counter }} />The component renders through a portal into a host element over the marker, so it is part of your app's tree:
context, StrictMode and Suspense reach it. While a document streams, a marker's block is re-created at every token; the
host stays, so the component is mounted once and receives new props. An island that throws is unmounted by its error
boundary, and its fallback shows again. Load heavy code lazily (React.lazy): the fallback stays visible until the
component paints.
Without a framework
mountTypstream, createHtmlRenderer and createPagedView (and mountPaged) take renderers, functions that mount
into the host and return update and destroy:
import { mountTypstream, type IslandRenderer } from "@typstream/dom";
const counterRenderer: IslandRenderer = (host, props) => {
const button = document.createElement("button");
let count = (props.data as CounterData).start;
button.textContent = `Count: ${count}`;
button.onclick = () => (button.textContent = `Count: ${++count}`);
host.append(button);
return {
update: (next) => (button.disabled = next.isIncomplete),
destroy: () => button.remove(),
};
};
mountTypstream(element, { engine, source, plugins: [counter], islands: { counter: counterRenderer } });Keep the islands object the same between updates: a new one mounts every island again.
Styling
- Paint your own background. The host is positioned over the fallback, which keeps its box (nothing moves when the
island mounts) and is hidden once the host has content; until then, while your code loads, it shows.
background: var(--typstream-island-background, Canvas)matches the page; the paged view sets white, the paper, and paints it under a host with content (the fallback is on the page's canvas there, so it can't be hidden, only covered). - The document's element rules reach in. The HTML renderer styles elements with zero specificity
(
:where(.typstream) svg { max-width: 100% }), so any class rule of yours overrides them; reset what you need. - Ship CSS as constructable stylesheets (
new CSSStyleSheet(),adoptedStyleSheetson the host's root node), or throughstylesheetson the mount: no<style>element, so a strict CSP needs nothing more. - Print hides islands and shows their fallbacks. So do exports: PDF, DOCX and standalone HTML are compiled from the document, where the island is its fallback.
Security
Treat data as untrusted: the document wrote it, and a model wrote the document.
- Check it in
parse. Render it as text (React escapes it); never as HTML or as a URL you load. - A marker's JSON is capped at 64 KB and a document mounts at most 50 islands; past either, fallbacks stay.
- An island fetches nothing the document names. Images and files come from
file(path), the same bytes Typst drew, which only your app'sresolveImagedownloads. - Only names a loaded plugin declares mount, so a document can't mount a component your app didn't pair with its plugin.
Accessibility
When an island mounts, its fallback is aria-hidden: assistive technology reads the island. On pages, that is the
text layer's text under the island. Give it a name (a figure with aria-label, say), keep its controls reachable by
keyboard, and set aria-busy while isIncomplete.
The paged target
The engine reports each marker's page, position and size (PagedArtifact.islands, the whole list with every paged
artifact), and the paged view mounts each island in a box over its page (.typstream-island-box, in a
.typstream-islands layer above the page's text layer and links). The box is as big as the marker's block: the
column's width and the fallback's height. Boxes are positioned in units of the page's width (cqw), so they follow the
page's scale (fixed, fit-width) with no script, and a page redrawn as the document streams leaves them be. An island
that moves, further down its page or onto the next one, keeps its host: the component isn't mounted again.
- The page itself is Typst's drawing. Islands are elements over the page's canvas (or SVG), never painted into it, so the canvas is what prints and what PDF and DOCX exports contain, and checks that compare pages with the PDF pixel by pixel (the browser suites' preview-vs-PDF check, plugins' paged conformance) compare the fallback.
isIncompletecomes from the marker'ssourceagainst heal's stable offset, as in the HTML target: while the document streams, an island whose source starts at or after it is still being written.- Text under an island (the fallback's labels in the text layer) is
aria-hiddenwhile the island is mounted, and can't be selected through it. - In the DOM, a page's islands come after its text layer, so a screen reader meets them at the end of their page.
Writing a plugin
Package your own Typst functions, styles, prompt rules and compile fixes as a typstream plugin, and load it in React, the DOM renderer or the engine.
Validating and repairing on the server
Check an LLM-written Typst document before you save it, ask the model to fix what doesn't compile, and render the result to PDF with @typstream/node.