white-label-view

Install and requirements

• Node.js ^22.18.0 or >=24.11.0 for installation/development/server rendering
• EventTarget-compatible models for observable model binding
• Browser DOM only for the default browser entrypoint
• No DOM globals required by white-label-view/server

import View from 'white-label-view';

import View from 'white-label-view/server';

import {html, attributes, unsafeHTML} from 'white-label-view/html';

Rendering contract

Browser View templates must resolve to exactly one DOM element, one tagged HTML value, or one compatible single-root HTML string. Invalid or multi-root output throws TypeError without replacing the last successful root.

Server View accepts tagged HTML values or compatible HTML strings and stores the most recently rendered HTML for toString(). It does not emulate DOM nodes, mounting, delegated events, focus, or animation frames.

import {html} from 'white-label-view/html';

const view = new View({
    parentElement: document.querySelector('main'),
    model,
    template: data => html`<section>${data.name}</section>`
}).initialize();

Browser lifecycle

initialize() performs a synchronous render. A successful mount/replacement establishes model binding, calls addListeners(), then afterMount(). Before replacement or destruction, removeListeners() runs and owned children are cleaned up.

An existing attached element can be adopted without a client template. View calls update(element, data) before requiring template output; return true to handle the render in place, or false to fall back to the configured template.

A View can also own both its rendered markup and the events bound to that markup. Delegated listeners registered through this.delegated are cleared when the root is replaced or the View is destroyed.

import {Model} from 'white-label-model';
import View from 'white-label-view';
import {html} from 'white-label-view/html';

const model = new Model({open: false});

class MenuView extends View {
    handleClick = () => model.update({open: !model.get().open});

    override addListeners() {
        this.delegated.on('click', '[data-menu-toggle]', this.handleClick);
        return this;
    }
}

const view = new MenuView({
    parentElement: document.querySelector('main')!,
    model,
    template(data) {
        const state = data as {open: boolean};
        return html`<section>
            <button type="button" data-menu-toggle>Toggle menu</button>
            <p>${state.open ? 'Open' : 'Closed'}</p>
        </section>`;
    }
}).initialize();

Model binding and batching

A model is treated as observable when it exposes addEventListener() and removeEventListener(). If it exposes get(), View passes get() to the template; otherwise it passes the model itself.

batchUpdates: true coalesces model-triggered browser renders into one requestAnimationFrame. Manual render() stays synchronous. Server rendering is always synchronous.

Tagged HTML and trust

The first-party html tagged template escapes ordinary interpolated text and quoted attribute values. attributes() validates attribute names, rejects intrinsic on* handlers and srcdoc, and escapes attribute values.

Tagged HTML and attribute helper values are recognized through runtime-owned identity that application code cannot reproduce with a marker-shaped object. unsafeHTML() is an explicit caller-owned trust boundary for markup that has already been independently trusted or sanitized. HTML escaping is not a URL, CSS, or application-policy sanitizer, so applications still validate context-sensitive values.

const template = data => html`<section>${data.name}</section>`;

Template engines

White Label View includes a small first-party tagged HTML template helper and otherwise stays renderer-agnostic. Applications that prefer a third-party renderer install, configure, and call it themselves; View does not bundle, configure, detect, or adapt third-party engines.

First-party tagged HTML

html escapes ordinary interpolated text and quoted attribute values. Use attributes() for conditional/opening-tag attributes and reserve unsafeHTML() for content that has already been independently trusted or sanitized.

import {html} from 'white-label-view/html';

const template = data => html`<article class="card">
    <h2>${data.title}</h2>
</article>`;

Tested third-party engines

Compatibility CI installs each renderer only in the test environment, wires it through the normal template(data) contract, and verifies its synchronous HTML output with both browser View and white-label-view/server. These engines are not White Label runtime dependencies.

Bring your own renderer

A renderer only needs to produce a value View already accepts: one DOM element in the browser, or an HTML string for browser/server rendering. Install and configure the renderer in the application, then call it from the View template.

npm install <your-template-engine>

const view = new View({
    parentElement,
    template: data => renderTemplate(data)
});

When a third-party renderer returns a string, that string is an application-owned trust boundary. Follow that renderer's escaping and trusted-markup rules before returning the result to View.

Serverless rendering

Use white-label-view/server when a function should return HTML. It requires no DOM globals and can turn request-scoped Model state into an HTML string before the invocation returns.

Create server View instances per request when they own request data or subscriptions. Browser View remains a separate progressive-enhancement layer and should not be emulated inside the serverless function.

Related guides

Focused guides for common implementation questions around this package.

• Add modern JavaScript to server-rendered apps without a rewrite
• Server-side rendering without a component framework

TypeScript

View.Settings and View.Model expose the EventTarget-based browser/server model contracts.

Template data is unknown by design; application code should narrow domain data before accessing fields. white-label-view/html exports the HTMLMarkup type for tagged output.

Security and trust boundaries

The html tag escapes ordinary dynamic text and quoted attribute values. attributes() validates names, rejects on* event-handler attributes and srcdoc, and escapes rendered attribute values. Tagged HTML and attribute values use package-instance-owned identity so arbitrary objects cannot forge trusted markup.

HTML escaping is not a URL or CSS sanitizer. Validate context-sensitive values separately. unsafeHTML(), application-owned HTML-string templates, third-party renderer output, and strings crossing package-copy boundaries are explicit caller-trusted inputs.

Design boundaries

View owns rendering mechanics and rendering lifecycle, not application state, routing, networking, CSS, sanitization policy, or application-wide events.

The browser entrypoint can adopt and update an existing root explicitly; it does not provide automatic hydration or claim to reconcile arbitrary server DOM with browser state.