lit-html

Efficient, Expressive, Extensible HTML templates in JavaScript

lit-html is the template system that powers the Lit library for building fast web components.

When using lit-html to develop web components, most users should import lit-html via the lit package rather than installing and importing from lit-html directly.

Documentation

Full documentation is available at lit.dev/docs/templates/overview/.

Overview

lit-html lets you write HTML templates in JavaScript with template literals.

lit-html templates are plain JavaScript and combine the familiarity of writing HTML with the power of JavaScript. lit-html takes care of efficiently rendering templates to DOM, including efficiently updating the DOM with new values.

import {html, render} from 'lit-html';

// This is a lit-html template function. It returns a lit-html template.
const helloTemplate = (name) => html`<div>Hello ${name}!</div>`;

// This renders <div>Hello Steve!</div> to the document body
render(helloTemplate('Steve'), document.body);

// This updates to <div>Hello Kevin!</div>, but only updates the ${name} part
render(helloTemplate('Kevin'), document.body);

lit-html provides two main exports:

• html: A JavaScript template tag used to produce a TemplateResult, which is a container for a template, and the values that should populate the template.
• render(): A function that renders a TemplateResult to a DOM container, such as an element or shadow root.

Installation

$ npm install lit-html

Or use from lit:

$ npm install lit

Contributing

Please see CONTRIBUTING.md.

2020-09-20

lit - 2.0.0

Major Changes

• New package serving as the main entry point for all users of Lit (including LitElement, ReactiveElement, and lit-html). See the Migration Guide for more details.

lit-element - 3.0.0

Major Changes

• Most users should no longer import directly from lit-element, and instead prefer importing LitElement from the lit packages. The default entry point for lit-element remains backward-compatible and includes all decorators. However, it's recommended to use import {LitElement} from 'lit'; and import decorators from lit/decorators as necessary. See the Upgrade Guide for more details.
• UpdatingElement has been moved from the lit-element package to the @lit/reactive-element package and renamed to ReactiveElement. See the ReactiveElement API documentation for more details. In addition, the source for css-tag, and all decorators have been moved to @lit/reactive-element. However, all symbols are re-exported from both lit and lit-element packages.
• The @internalProperty decorator has been renamed to @state.
• Errors that occur during the update cycle were previously squelched to allow subsequent updates to proceed normally. Now errors are re-fired asynchronously so they can be detected. Errors can be observed via an unhandledrejection event handler on window.
• The lib folder has been removed.
• Rendering of renderRoot/shadowRoot) via createRenderRoot and support for static styles has moved from LitElement to ReactiveElement.
• The createRenderRoot method is now called just before the first update rather than in the constructor. Element code can not assume the renderRoot exists before the element hasUpdated. This change was made for compatibility with SSR.
• ReactiveElement's initialize method has been removed. This work is now done in the element constructor.
• The static render has been removed.
• For consistency, renamed _getUpdateComplete to getUpdateComplete.
• When a property declaration is reflect: true and its toAttribute function returns undefined the attribute is now removed where previously it was left unchanged (#872).
• The dirty check in attributeChangedCallback has been removed. While technically breaking, in practice it should very rarely be (#699).
• LitElement's adoptStyles method has been removed. Styling is now adopted in createRenderRoot. This method may be overridden to customize this behavior.
• LitElement's static getStyles method has been renamed to static finalizeStyles and now takes a list of styles the user provided and returns the styles which should be used in the element. If this method is overridden to integrate into a style management system, typically the super implementation should be called.
• Removed build support for TypeScript 3.4.
• Decorators are no longer exported from the lit-element module. Instead, import any decorators you use from lit/decorators/*.
• lit-html has been updated to 2.x.
• Support for running in older browsers has been removed from the default configuration. Import the platform-support module to support Shady DOM. Note also that Lit parts inside <style> elements are no longer supported. See Polyfills for more details.
• For simplicity, requestUpdate no longer returns a Promise. Instead await the updateComplete Promise.
• Removed requestUpdateInternal. The requestUpdate method is now identical to this method and should be used instead.

• #2103 15a8356d - Updates the exports field of package.json files to replace the subpath folder mapping syntax with an explicit list of all exported files.

  The /-suffixed syntax for subpath folder mapping originally used in these files is deprecated. Rather than update to the new syntax, this change replaces these mappings with individual entries for all exported files so that (a) users must import using extensions and (b) bundlers or other tools that don't resolve subpath folder mapping exactly as Node.js does won't break these packages' expectations around how they're imported.

Minor Changes

• A public renderOptions class field now exists on LitElement and can be set/overridden to modify the options passed to lit-html.
• Adds static shadowRootOptions for customizing shadowRoot options. Rather than implementing createRenderRoot, this property can be set. For example, to create a closed shadowRoot using delegates focus: static shadowRootOptions = {mode: 'closed', delegatesFocus: true}.
• Adds development mode, which can be enabled by setting the development Node exports condition. See Development and production builds for more details.

Patch Changes

• #1964 f43b811 - Don't publish src/ to npm.
• For efficiency, the css function now maintains a cache and will use a cached value if available when the same style text is requested.
• Fixed reflecting a property when it is set in a setter of another property that is called because its attribute changed (#965).
• Fixed exceptions when parsing attributes from JSON (#722).
• Fixed issue with combining static get properties on an undefined superclass with @property on a subclass ([#890]https://github.com/Polymer/lit-element/issues/890));

@lit/reactive-element - 1.0.0

Major Changes

• @lit/reactive-element is a new package that factors out the base class that provides the reactive update lifecycle based on property/attribute changes to LitElement (what was previously called UpdatingElement) into a separate package. LitElement now extends ReactiveElement to add lit-html rendering via the render() callback. See ReactiveElement API for more details.
• UpdatingElement has been renamed to ReactiveElement.
• The updating-element package has been renamed to @lit/reactive-element.
• The @internalProperty decorator has been renamed to @state.
• For consistency, renamed _getUpdateComplete to getUpdateComplete.
• When a property declaration is reflect: true and its toAttribute function returns undefined the attribute is now removed where previously it was left unchanged (#872).
• Errors that occur during the update cycle were previously squelched to allow subsequent updates to proceed normally. Now errors are re-fired asynchronously so they can be detected. Errors can be observed via an unhandledrejection event handler on window.
• ReactiveElement's renderRoot is now created when the element's connectedCallback is initially run.
• Removed requestUpdateInternal. The requestUpdate method is now identical to this method and should be used instead.
• The initialize method has been removed. This work is now done in the element constructor.

Minor Changes

• Adds static addInitializer for adding a function which is called with the element instance when is created. This can be used, for example, to create decorators which hook into element lifecycle by creating a reactive controller (#1663).
• Added ability to add a controller to an element. A controller can implement callbacks that tie into element lifecycle, including connectedCallback, disconnectedCallback, willUpdate, update, and updated. To ensure it has access to the element lifecycle, a controller should be added in the element's constructor. To add a controller to the element, call addController(controller).
• Added removeController(controller) which can be used to remove a controller from a ReactiveElement.
• Added willUpdate(changedProperties) lifecycle method to UpdatingElement. This is called before the update method and can be used to compute derived state needed for updating. This method is intended to be called during server side rendering and should not manipulate element DOM.

lit-html - 2.0.0

Major Changes

• The templateFactory option of RenderOptions has been removed.
• TemplateProcessor has been removed.
• Symbols are not converted to a string before mutating DOM, so passing a Symbol to an attribute or text binding will result in an exception.
• The shady-render module has been removed and is now part of platform-support, and Lit's polyfill support now adds the following limitations: (1) Bindings in style elements are no longer supported. Previously these could not change and in the future they may be supported via static bindings. (2) ShadyCSS.styleElement is no longer called automatically. This must be called whenever dynamic changes that affect styling are made that involve css custom property shimming (older browsers) or changes to custom properties used via the deprecated @apply feature. It was previously called only on first render, and it is now up to the user to decide when this should be called. See Polyfills for more details.
• render() no longer clears the container it's rendered to. It now appends to the container by default.
• Expressions in comments are no longer rendered or updated. See Valid expression locations for more details.
• Template caching happens per callsite, not per template-tag/callsize pair. This means some rare forms of highly dynamic template tags are no longer supported.
• Arrays and other iterables passed to attribute bindings are not specially handled. Arrays will be rendered with their default toString representation. This means that html`<div class=${['a', 'b']}> will render <div class="a,b"> instead of <div class="a b">. To get the old behavior, use array.join(' ').
• Multiple bindings in a single attribute value don't require the attribute value is quoted, as long as there is no whitespace or other attribute-ending character in the attribute value. html`<div id=${a}-${b}>`
• The directive and part APIs are significantly different. See Custom Directives and the Upgrade Guide for more details.
• The Directive base class and directive() factory function are now exported from the lit-html/directive.js module.
• NodePart has been renamed to ChildPart, along with other methods and variables that use the "Node" naming, like PartType.Node which is now PartType.CHILD.
• The part exports (ChildPart, AttributePart, etc) have been change to interface-only exports. The constructors are no longer exported. Directive authors should use helpers in directive-helpers.js to construct parts.
• The eventContext render option has been changed to host.

• #2103 15a8356d - Updates the exports field of package.json files to replace the subpath folder mapping syntax with an explicit list of all exported files.

  The /-suffixed syntax for subpath folder mapping originally used in these files is deprecated. Rather than update to the new syntax, this change replaces these mappings with individual entries for all exported files so that (a) users must import using extensions and (b) bundlers or other tools that don't resolve subpath folder mapping exactly as Node.js does won't break these packages' expectations around how they're imported.

• #1764 0b4d6eda - Don't allow classMap to remove static classes. This keeps classMap consistent with building a string out of the classnames to be applied.

Minor Changes

• Added renderBefore to render options. If specified, content is rendered before the node given via render options, e.g. {renderBefore: node}.
• Added development mode, which can be enabled by setting the development Node exports condition. See Development and production builds for more details.
• All usage of instanceof has been removed, making rendering more likely to work when multiple instances of the library interact.
• Template processing is more robust to expressions in places other than text and attribute values.
• render now returns the ChildPart that was created/updated by render.
• Added AsyncDirective, which is a Directive subclass whose disconnected callback will be called when the part containing the directive is cleared (or transitively cleared by a Part higher in the tree) or manually disconnected using the setConnected API, and whose reconnected callback will be called when manually re-connected using setConnected. When implementing disconnected, the reconnected callback should also be implemented to return the directive to a usable state. Note that LitElement will disconnect directives upon element disconnection, and re-connect directives upon element re-connection. See Async directives for more details.
• Added setConnected(isConnected: boolean) to ChildPart; when called with false, the disconnected callback will be run on any directives contained within the part (directly or transitively), but without clearing or causing a re-render to the tree. When called with true, any such directives' reconnected callback will be called prior to its next update/render callbacks. Note that LitElement will call this method by default on the rendered part in its connectedCallback and disconnectedCallback.
• Added the static-html module, a static html tag function, a literal tag function, and unsafeStatic(), which allows template authors to add strings to the static structure of the template, before it's parsed as HTML. See Static expressions for more details.
• Added lit-html/directive-helpers.js module with helpers for creating custom directives. See Custom directives for more details.
• Rendering null, undefined, or empty string in a ChildPart now has the same affect as rendering nothing: it does not produce an empty text node. When rendering into an element with Shadow DOM, this makes it harder to inadvertently prevent <slot> fallback content from rendering.
• Nested directives whose parent returns noChange are now unchanged. This allows the guard directive to guard directive values (#1519).
• Added optional creationScope to RenderOptions, which controls the node from which the template is cloned from.
• Added support for running with Trusted Types enforced.

Patch Changes

• #1922 8189f094 - Binding noChange into an interpolated attribute expression now no longer removes the attribute on first render - instead it acts like an empty string. This is mostly noticable when using until() without a fallback in interpolated attributes.

• #1964 f43b811 - Don't publish src/ to npm.

• #2070 a48f39c8 - Throw instead of rendering an innocuous value into a style or script when security hooks are enabled.

• #2044 662209c3 - Improves disconnection handling for first-party AsyncDirectives (until, asyncAppend, asyncReplace) so that the directive (and any DOM associated with it) can be garbage collected before any promises they are awaiting resolve.