Putting type
on your page.

What driftype is

Type rendered as a signed distance field rather than as glyphs. The whole line is one continuous surface, so letters can swell into each other and weld, a word can morph into a different word through the field rather than cross-fading, and effects operate on the shape itself — eroded, hollowed, beaded into liquid pixels.

None of that is available to anything that rasterises glyphs and composites them, which is most of the alternatives. It is also not a video: it runs live on the GPU in about 1.6 MB, at whatever size the page gives it, and it responds to a click or the pointer if the piece says it should.

It is for the type on a page that is the point — a wordmark, a hero, a title card, a piece of art. It is not a way to render text in general, and specifically not a way to render labels, navigation, body copy or the text inside a control. See By design, not yet.

How a piece gets made

You author in the editor — text, a sequence of states, a look assembled from the preset vocabulary — and export. The export is a self-contained document: the glyph geometry travels inside it, so the piece renders on a machine that has never seen the font and renders the same way in a year. That file is what you point this element at.

What you need

Two files, which must sit in the same directory. The engine resolves its binary as new URL("driftype.wasm", import.meta.url), so moving one without the other breaks it — unless you hand it the bytes yourself, see Without a server.

Two entry points, because registering a custom element is a side effect and a <script> tag cannot call a function. -auto.js is two lines that register <drift-type> for you; importing driftype-embed.js registers nothing and exports define(), so a bundler decides when — and under what tag name.

import { define } from "./driftype-embed.js";
define();                 // <drift-type>
define("hero-type");      // or your own name

Plus your document — a self-contained .json that carries its own glyph geometry. A short wordmark runs about 7 KB. Nothing fetches a font at runtime.

Browser support

WebGPU is required — Chrome and Edge, or Safari 26 and later. Anywhere it is missing, the element shows its fallback content and reports why on the console. Support elsewhere is moving; test rather than assume.

Getting started

1. Build the embed

   From a driftype checkout:

   # Writes dist/: the bundle, the wasm, example.html with its example.json,
   # and driftype-embed.zip holding all of it plus this guide.
   ./build.sh --embed

   This is a different build from the editor's, not a repackaging of it. It drops the preloaded fonts, which is what takes the payload from 24.5 MB to 1.61 MB. Embedded documents carry their own geometry and never open a font file.

2. Export a document

   Author in the editor and use its export button, or export a document you already have headlessly, with the server running:

   ./run_server.sh &
   ./capture.sh "name=hero&export=1" my-piece.json
   # -> capture/input/hero.json

   Name the document. Without one, capture.sh exports its own test sequence, set in Arial Unicode — a font whose outlines you may not redistribute. To see the whole path work before you have a piece, the build already ships one: example.json, set in Anton under the SIL Open Font License, with Anton-OFL.txt beside it.

   Export is what makes the document portable: the glyphs are decomposed and embedded, so the file renders in a session that never loads a font. Copy it next to your page as hero.json.

3. Add the tag

   <script type="module" src="driftype-embed-auto.js"></script>
   
   <drift-type src="hero.json" width="1000" height="400">
     Calm, then urgent
   </drift-type>

   That is the whole integration. Four files in a directory:

   index.htmlyour page

   driftype-embed.js165 KB

   driftype.wasm1.45 MB

   hero.json~7 KB

The element

<drift-type> takes three attributes. Its children are the fallback.

The fallback is the point

Whatever you put inside the tag stays visible until a frame is actually going to be drawn, and comes back if anything fails afterwards. A browser without WebGPU, a document that no longer validates, a 404 on src — all of them leave your text on the page and print the reason on the console.

Put the real words there, not a placeholder. It is what a reader sees when the canvas cannot run.

Sizing and sharpness

width and height work exactly as they do on <img>. They are an intrinsic size that also supplies the aspect ratio, and CSS overrides them. An embed in a narrower column shrinks rather than overflowing; a page that asks for more gets more; set only a height and the width follows from the ratio.

/* Smaller: put it in a narrower container, or size the element. */
drift-type { width: 320px; }

/* Larger than the attribute: the same way. */
drift-type { width: 900px; }

/* Full bleed, aspect ratio kept. */
drift-type { width: 100%; }

/* Height only — width follows from the ratio, as on an img. */
drift-type { height: 120px; width: auto; }

/* Both — an explicit box wins and the ratio yields. */
drift-type { width: 500px; height: 300px; }

The element is display: block with max-width: 100% and the aspect ratio by default, installed as a stylesheet rule rather than an inline style so an ordinary selector beats it. The canvas then fills the element exactly, whatever box it ends up with. The backing store is the size it is actually laid out at, times the display's pixel ratio — read after layout, never assumed from the attributes.

Pixel ratio is capped at 2×. Not for fill rate — the field margin scales with device pixels, and the glyph store's capacity falls off with the square of that margin, so a 3× display could run a long document out of glyphs for very little visible return.

Resizing

A resize is a re-warm, not a resize. Type size is derived from canvas height, so every glyph in the store was baked at the old one and has to be thrown away and regenerated. The element handles this — a ResizeObserver, debounced 150 ms, plus a media query that catches a window dragged onto a display with a different pixel ratio, which changes nothing about the CSS size and so fires no resize event.

The clock does not move. A piece three quarters of the way through a transition comes back three quarters of the way through it.

Scripting it

The element forwards the player's own verbs. These are the same four the editor drives, so a piece you script and a piece driven by its own triggers go through one path.

const hero = document.querySelector("drift-type");

hero.play();
hero.pause();
hero.toggle();
hero.restart();

hero.playing;  // boolean, false before it is ready

Events

hero.addEventListener("drift-ready", (e) => {
  console.log("cycle", e.detail.cycle, "ms");
});

hero.addEventListener("drift-error", (e) => {
  // The fallback is already visible. Log it, or swap in your own.
  console.warn("driftype:", e.detail.message);
});

What drift-error covers

Every failure the element can detect, not only the ones during load: a missing or malformed document, a font that will not restore, a failure while resizing, anything thrown by the engine on a frame, and the GPU device being lost. In all of them the canvas is removed and your fallback content is put back before the event fires, so the element never sits there as a blank or frozen rectangle.

One case is deliberately not an error. A GPU validation warning is reported to the console and the element keeps rendering, because those are usually survivable and tearing the piece down over one would be a worse outcome than whatever artefact it warns about.

Triggers live in the document

A document can bind its own interactions, and the element wires them to the canvas for you. You do not add listeners for these. The events it can bind are click, pointer_enter and pointer_leave; the actions are these:

Sitting over your page

A document can declare surface.mode: "transparent", and the canvas then carries an alpha channel so whatever is behind it shows through. This is a property of the whole piece rather than of one state — the canvas is one surface, so it cannot be transparent for one word and opaque for the next.

The preset's background knob is still declared and still crosses between states; the runtime simply does not paint it. That means a document authored opaque can be exported transparent without touching its presets.

Several on one page

Supported, and cheap. The WebAssembly module — the expensive part — is instantiated once per page and shared; each element gets its own rendering context beside it.

Each element also drives its own requestAnimationFrame rather than the engine's internal loop. That detail matters more than it sounds: a module has exactly one main loop, and an earlier version that used it aborted the whole runtime the moment a second <drift-type> appeared — taking the first one down with it. A page with a header and a footer is not an exotic case.

Layering, and the sync attribute

Stacking elements is how you build what one document cannot express — a chromatic offset, a parallax pair, a blurred copy behind a sharp one. It only works if the layers are in register, and by default they are not: each element starts its clock when its own warm finishes, so two instances of the same document sit permanently out of phase by the difference in their boot times. Measured at 31ms, and different on every load, because it depends on when each document happened to arrive.

sync puts them on one clock. With no value it groups by src, which is the layering case — several elements showing one piece:

<div class="stack">
  <drift-type src="hero.json" sync></drift-type>
  <drift-type src="hero.json" sync></drift-type>
</div>

Give it a value to group layers built from different documents that still have to move together — sync="hero" on each.

The first element in a group fixes the clock and the rest adopt it. One added later — a lazy load, a route change — adopts it too and steps forward to catch up, so it arrives already in phase rather than starting from the beginning. Both clocks are caught up: the document's position, and the engine's own accumulator, which is what a knob like ripple_speed reads.

Without a server

A page opened straight from disk — a file someone was sent, a demo on a stick, this guide inside the zip — cannot fetch anything. The browser refuses a module script with a src, the engine's request for driftype.wasm, and the element's request for its document. WebGPU itself is fine there: file:// counts as a secure context. So the page has to carry everything, and the element takes both halves directly.

The live example at the top of this guide is built exactly this way, which is why it plays when you open the file from the archive. Its source is the working reference.

The document, inline

Put the exported document inside the element as a <script type="application/json"> and leave out src. A script element is never rendered, so it sits beside the fallback without becoming part of it.

<drift-type width="1000" height="400">
  <script type="application/json">{ "schema": 3, ... }</script>
  Calm, then urgent
</drift-type>

One of the two, never both. An element with a src and an inline document is refused rather than guessing which one you meant, and so is a bare sync on an inline document — it groups by src, and there is none. Name the group instead: sync="hero".

The HTML parser ends a script at the first </script, whatever the JSON around it says. Exported glyph data cannot contain one, but text can; if yours does, write it as <\/script, which is the same string to JSON.

The engine, handed over

define() takes the wasm bytes as an option, and the engine then never goes looking for the file. An ArrayBuffer, a typed array, or a promise of either — a promise so the bytes can still be decompressing when you call it.

import { define } from "./driftype-embed.js";

// Gzipped base64 in the page: about 630 KB, against 2 MB unzipped.
const text = document.getElementById("driftype-wasm").textContent.trim();
const gzipped = Uint8Array.from(atob(text), (c) => c.charCodeAt(0));
const wasm = new Response(
  new Blob([gzipped]).stream().pipeThrough(new DecompressionStream("gzip"))
).arrayBuffer();

define("drift-type", { wasm });

The import above is for your bundler, not the browser: from file:// the page cannot load that module either, so the bundle has to end up inline in a <script type="module"> too. How the wasm gets into the page is up to your build — the base64 element above is what the example uses.

What it costs

Every standalone page carries its own copy of the engine — the example page is about 840 KB — and nothing is shared or cached between two of them. It is also frozen: an engine fix reaches a page served from files the next time you replace the wasm, and never reaches a standalone file already sent. If you can serve files, serve them.

When it does not work

Every failure the element can see leaves the fallback visible and prints a reason prefixed [drift-type]; driftype's own warnings say [driftype]. The first row below is the one failure the element cannot see, because it never got to run. These are the ones you are most likely to meet.

By design, not yet

A few limits are deliberate, and knowing which is which saves you looking for a switch that does not exist.

• Not for UI text. A label, a menu item, a paragraph or the text inside a <button> should be real text styled with CSS. A control's words have to be readable by a screen reader, selectable, findable with your browser's find and translatable, and canvas text is none of those — the fallback carries the real words, so the accessible copy is the one hidden whenever the rendering works. A document's character set is closed and its outlines are baked in, so a label that changes at runtime — a count, a name, Add becoming Added — cannot be expressed at all. The rendering context is per element, so twenty of these is twenty GPU devices and twenty frame loops to draw a few words. And the element has a declared aspect ratio, so it cannot grow to fit a longer label the way a button does.
• One font per document. The schema has a single font block. Two typefaces means two documents.
• No custom shaders. Looks come from the published preset vocabulary. Shipping a shader extension point means shipping a public contract on uniform and buffer layout, which is not on the table at this stage.
• No pixel canvas in the document. Type size is a fraction of container height, so one document renders correctly at any size instead of letterboxing away from the size it was authored at.
• Rendering is a pure function of the document. Same document, same elapsed time, same frame — on any machine, at any real speed. Seeds live in the document; nothing is resolved at runtime.