DOMRenderer

A renderer for browser DOM environments.

Syntax

class DOMRenderer extends Renderer<Node, string, Element> {
  constructor();

  render(
    children: Children,
    root: Element,
    ctx?: Context
  ): Promise<ElementValue<Node>> | ElementValue<Node>;

  hydrate(
    children: Children,
    root: Element,
    ctx?: Context
  ): Promise<ElementValue<Node>> | ElementValue<Node>;
}

Constructor

new DOMRenderer()

Creates a new DOMRenderer instance. In most cases, you should use the pre-instantiated renderer export instead.

Instance methods

render()

render(children, root, ctx?): Promise<ElementValue<Node>> | ElementValue<Node>

Renders an element tree into a DOM element.

Parameters:

children - Children - The element tree to render. Pass null to unmount.
root - Element - The DOM element to render into.
ctx (optional) - Context - An ancestor context for bridging renderers.

Returns: The rendered DOM nodes, or a promise if the tree is async.

Throws: TypeError if root is not a DOM element node.

hydrate()

hydrate(children, root, ctx?): Promise<ElementValue<Node>> | ElementValue<Node>

Hydrates server-rendered HTML by attaching event handlers and reconciling state.

Parameters:

children - Children - The element tree matching the server-rendered HTML.
root - Element - The DOM element containing server-rendered content.
ctx (optional) - Context - An ancestor context for bridging renderers.

Returns: The hydrated DOM nodes, or a promise if the tree is async.

Throws: TypeError if root is not a DOM element node.

Description

DOMRenderer is the standard renderer for browser applications. It extends the base Renderer class with DOM-specific behavior:

Creates DOM elements from string tags
Handles SVG and MathML namespaces automatically
Maps props to DOM attributes and properties
Manages event listeners
Supports hydration of server-rendered HTML

The renderer validates that the root is a DOM element node and will throw if you pass the document, body, head, or documentElement directly (with a warning).

Examples

Basic rendering

import {DOMRenderer} from "@b9g/crank/dom";

const renderer = new DOMRenderer();

function App() {
  return <div>Hello, World!</div>;
}

renderer.render(<App />, document.getElementById("root"));

Using the pre-instantiated renderer

import {renderer} from "@b9g/crank/dom";

function App() {
  return <div>Hello, World!</div>;
}

// Simpler - no need to instantiate
renderer.render(<App />, document.getElementById("root"));

Updating and unmounting

import {renderer} from "@b9g/crank/dom";

const root = document.getElementById("root");

// Initial render
renderer.render(<App count={0} />, root);

// Update
renderer.render(<App count={1} />, root);

// Unmount
renderer.render(null, root);

Hydration

import {renderer} from "@b9g/crank/dom";

// HTML was server-rendered:
// <div id="root"><div class="app">Hello, World!</div></div>

function App() {
  return <div class="app">Hello, World!</div>;
}

// Hydrate attaches event handlers without replacing DOM
renderer.hydrate(<App />, document.getElementById("root"));

Async rendering

import {renderer} from "@b9g/crank/dom";

async function AsyncApp() {
  const data = await fetchData();
  return <div>{data.message}</div>;
}

// Returns a promise for async components
const result = await renderer.render(<AsyncApp />, document.getElementById("root"));

API Reference