lit-html is now part of the Lit library–see the new site at lit.dev. This site documents lit-html 1.0, not the latest version.

lit-html 1.2.0

See the changelog for a complete list of changes.

live directive

Documentation

The live directive solves the problem of DOM state changing from underneath lit-html, for example with an <input> that a user can type into:

html`<input .value=${live(x)}>`

In some cases you will want x to overwrite what the user has typed in. lit-html tracks the previous value of a binding and only updates the DOM if the value has changed. Without the live directive, lit-html will not detect that the value property of the input has changed and won't update the DOM.

The live directive ignores the previous value of the binding and always checks the current value in the DOM, causing the binding to update the input.

We still recommend that you handle user input so that the state and the DOM agree:

let text = '';
const onInput = (e) => {
  text = e.target.value;
  go();
};

const go = () => {
  render(html`<input .value=${text} @input=${onInput}>`, document.body);
}
go();

templateContent directive

Documentation

The templateContent directive lets you stamp out HTML templates into lit-html templates. This is useful in a number of cases where HTML <template> elements are provided by users of elements or parts of a build system.

HTML:

<template id="example">
  <p>HTML Template</p>
</template>

JavaScript:

const template = document.querySelector('#example');
html`
  <h1>Example</h1>
  ${templateContent(template)}
`;

unsafeSVG directive

Documentation

unsaveSVG is the missing partner of unsafeHTML. It lets you render a frangment of SVG text as SVG elements rather than text. As with unsafeHTML this directive not safe to use with user-provided input, since if the input has <script> tags in it, there may be ways to get them to execute, etc.

unsafeSVG creates elements in the SVG namespace, so it's for use inside of <svg> tags or inside of lit-html svg templates. If the input contains an <svg> tag itself, continute to use unsafeHTML.

// shape is SVG partial text, with no <svg> element
const renderShape = (shape) => html`
  <svg  width="100" height="100" viewBox="0 0 100 100">
    ${unsafeSVG(shape)}
  </svg>
`;