How-to
Website
Web app
Desktop / phone
Hand an element to a script
A library that draws into an element (a chart, a map, an editor, an effect) needs the element when it is made, new values while it lives, and a chance to stop when it goes. The three lifetime props give it each, on any element or component call. This page hands a paragraph to a script that types a greeting into it, retypes it when the name changes, and stops its timer when the paragraph leaves:
Needs: the script src/typewriter.js, shown below.
page Welcome(path: "/welcome", title: "Welcome", description: "A greeting a script types out, letter by letter.") {
state name = "reader"
state typing = true
Heading("Welcome").h1
Input(bind: name, label: "Your name")
Switch(bind: typing, label: "Type the greeting")
if typing {
Host(tag: "p",
mount: (node) => startTypewriter(node, "Hello, {name}."),
update: (writer) => writer.retype("Hello, {name}."),
cleanup: (writer) => writer.stop())
}
}
The script is a plain file under src/ (Call your own JavaScript):
// src/typewriter.js
/**
* Type `text` into `node`, one letter every 60 ms.
* @param {HTMLElement} node
* @param {string} text
*/
function startTypewriter(node, text) {
let shown = 0;
const timer = setInterval(() => {
if (shown < text.length) node.textContent = text.slice(0, ++shown);
}, 60);
return {
retype(next) { text = next; shown = 0; node.textContent = ""; },
stop() { clearInterval(timer); },
};
}
How it works
mount: (node) => …runs each time the element is made: the first paint, a route change, anifbranch arriving, a list item added. What it returns is the handle the other two receive. Here the handle is the object withretypeandstop.update: (handle) => …runs again whenever the state it reads changes. It readsname, so typing in the field retypes the greeting.cleanup: (handle) => …runs when the element leaves (its page, its branch or its list item), so nothing a library made outlives it. Turning the switch off removes the branch, andstopclears the timer.
A mount: that throws removes itself and logs the error; the page stays up.
To get a bare node for a library, use Host, as this page does. It has the same lifetime: Host(tag: "canvas", …) makes the element the library wants. It makes a div by default, or a span, canvas, svg, section, figure, pre, p, ul or table.
Troubleshooting
| What you see | What to do |
|---|---|
|
|
The script threw on mount; the message after it is the script's own error |
|
|
Use one of the tags |
| A timer or listener keeps running after the page changes |
Stop it in |
Variations
The three props work on every element, not only Host: Card(mount: (n) => initTilt(n)) hands the card itself to a script. On a component call, they belong to the component's root element, unless the component declares a prop of that name itself.