html API

How to use the html function to define what a component should render and create custom templates.

Description

html is Wompo's template tag. Components return it to describe their DOM structure.

const template = html`<p>Hello</p>`;

Because it is a tagged template, use backticks instead of calling it like a normal function.

Dynamic values

You can interpolate text, numbers, arrays, other templates, attributes, event handlers, refs, styles, and dynamic tags.

const staticTemplate = html`<i>I am static</i>`;

const dynamicTemplate = html`
  <div>
    <p>Static template: ${staticTemplate}</p>
    <p>Number: ${0}</p>
    <p>String: ${'ciao!'}</p>
    <p>Array: ${[0, 1, 2, 'three', html`four`]}</p>
    <p>Nested template: ${html`Look!`}</p>
    <p>${true && 'I am visible!'}</p>
    <p>${null} ${undefined} ${false}</p>
  </div>
`;

Falsy values are ignored, except for numbers and strings.

function Component() {
  return dynamicTemplate;
}

Interpolation cheatsheet

  • name=${value} sets or removes an attribute. On custom elements, camelCase names become kebab-case.
  • @event=${handler} attaches an event listener.
  • .prop=${value} assigns a DOM property instead of an attribute.
  • ref=${aRef} stores the DOM element in aRef.current.
  • style=${styleObject} accepts camelCase CSS properties; numeric values receive px.
  • <${tag}>...</${tag}> renders a dynamic tag.
  • <el ${attrs({ ... })}> spreads attributes, events, and properties from an attrs bag.