Skip to main content

The DOM Shim

Each widget has its own small DOM: a subset of the browser's Node, Element and Event API, enough for Preact to render into. You'll mostly meet it through refs and event handlers, but you can also build a widget with it directly, no Preact needed:

const widget = createWidget({ style: "hud", interactive: true });
const doc = widget.document;

const button = doc.createElement("button");
button.textContent = "Ping";
button.style.padding = "4px 8px";
button.addEventListener("click", () => console.log("pong"));

widget.root.appendChild(button);

How changes reach the client​

  • Only what's under the root is on the client. Creating a node, or building a whole subtree away from the root, sends nothing. Inserting it under the root sends the subtree in one go. Removing it drops it from the client.
  • Changes are batched. Everything you change during one task goes to the client in one message, once your code yields.
  • Unchanged values aren't sent. Setting an attribute, a style property or a text node's data to the value it already has does nothing.
  • Nodes belong to their widget. A node can only be inserted into the widget whose document created it. Inserting it into another widget throws.

Nothing comes back from the client except input. There's no layout, so no sizes, positions or computed styles.

UiDocument​

widget.document, and every node's ownerDocument.

MemberDescription
documentElementThe widget's root, a div. The same as widget.root.
bodyThe same as documentElement.
createElement(tag)A new HTML element.
createElementNS(namespace, tag)A new element in a namespace. SVG and MathML only draw in the web flavor.
createTextNode(data)A new text node.
createComment(data)A new comment. Comments are never sent to the client.

There's no global document. Reach the document through widget.document or a node's ownerDocument.

UiNode​

The base of elements, text nodes and comments.

Tree​

MemberDescription
nodeType1 for elements, 3 for text, 8 for comments.
nodeNameThe upper case tag for HTML elements, #text, or #comment.
ownerDocumentThe document that created it.
parentNode, parentElementIts parent, or null.
childNodesIts children. Live, so don't change the array.
firstChild, lastChild
nextSibling, previousSibling
isConnectedWhether it's under the widget's root, so on the client.
textContentThe text of it and its subtree. Setting it on an element replaces every child with one text node.
hasChildNodes()
contains(other)Whether other is this node or under it.

Changing the tree​

MethodDescription
appendChild(node)Insert node last. A node that's already somewhere is moved.
insertBefore(node, ref)Insert node before ref, or last if ref is null.
append(...nodes)Insert nodes, and strings as text nodes, last.
removeChild(node)
replaceChild(node, old)Put node where old is.
remove()Take it out of its parent.

Text nodes and comments can't have children.

Events​

MethodDescription
addEventListener(type, listener, options?)options is { capture?, once? }, or a boolean for capture. listener is a function or an object with handleEvent.
removeEventListener(type, listener, options?)
dispatchEvent(event)Run the listeners through the capture and bubble phases, as in a browser. Returns false if one called preventDefault().

The first listener for a type on an element tells the client to start sending that type for it, and removing the last one tells it to stop. A listener that throws is logged, and the rest still run.

UiElement​

MemberDescription
localNameThe tag, lower case for HTML elements. SVG ones keep their case (linearGradient).
tagNameUpper case for HTML elements.
namespaceURI
childrenChild elements only.
id, classNameThe id and class attributes.
styleThe inline style, see UiStyle.
getAttribute(name), hasAttribute(name), getAttributeNames()
setAttribute(name, value)style goes through style.cssText.
removeAttribute(name)
toggleAttribute(name, force?)Returns whether the attribute is there afterwards.
valueA control's value. See below.
checkedWhether a checkbox or radio is ticked. The same as the checked attribute.

HTML attribute names are case insensitive, as in a browser.

value is the value attribute. Unlike a browser, the attribute and the current value are one and the same, and the client keeps both in sync as the player types or picks. Without the attribute, a select's value is its first option's, and an option's or textarea's is its text.

Not supported: innerHTML (there's no HTML parser, it throws), querySelector and friends, classList, dataset, focus(), click(), getBoundingClientRect() and anything else that reads the layout.

UiStyle​

An element's inline style, a subset of CSSStyleDeclaration.

MemberDescription
setProperty(name, value)name is kebab case, or a custom property (--name). An empty or null value removes it.
removeProperty(name)Returns the old value.
getPropertyValue(name)"" when not set.
cssTextEvery property as text. Setting it replaces them all.
lengthHow many properties are set.

Properties can also be read and set camel cased, the way Preact does:

el.style.backgroundColor = "var(--surface)";
el.style.setProperty("--accent", "var(--primary)");

Which properties the client draws depends on the flavor. See Lite CSS, or anything in the web flavor.

UiText and UiComment​

A UiText has data (and nodeValue, the same thing). Setting it updates the text on the client.

A UiComment has data too, but is never sent to the client. Comments are kept in the tree so libraries that use them as markers still work.

UiEvent​

What event listeners, and Preact's on... handlers, receive. You can create your own with new UiEvent(type, { bubbles?, cancelable? }) and dispatch it.

MemberDescription
type
bubbles, cancelable
targetThe node it was dispatched on.
currentTargetThe node whose listener is running.
eventPhaseUiEvent.CAPTURING_PHASE, AT_TARGET, BUBBLING_PHASE, or NONE outside a dispatch.
timeStampWhen it was created, in milliseconds since the epoch.
defaultPrevented
preventDefault()Sets defaultPrevented if it's cancelable. Nothing on the client acts on it.
stopPropagation()Stop it reaching other nodes. The current node's other listeners still run.
stopImmediatePropagation()Stop it reaching any other listener.
composedPath()The target and its ancestors, target first.

Events from the web flavor also carry pointer, key, wheel and modifier fields when the browser event had them.