Using lit-html standalone
lit-html, which can be used outside of the Lit component model anywhere you need to efficiently render and update HTML.
lit-html standalone packagePermalink to “lit-html standalone package”
lit-html package can be installed separately from
The main imports are
lit-html package also includes modules for the following features described in the full
Lit developer guide:
lit-html/directives/*- Built-in directives
lit-html/directive.js- Custom directives
lit-html/async-directive.js- Custom async directives
lit-html/directive-helpers.js- Directive helpers for imperative updates
lit-html/static.js- Static html tag
lit-html/polyfill-support.js- Support for interfacing with the web components polyfills (see Styles and lit-html templates)
Rendering lit-html templatesPermalink to “Rendering lit-html templates”
html tag. The contents of the literal are mostly plain, declarative HTML, and may include expressions to insert and update the dynamic parts of a template (see Templates for a full reference on Lit's templating syntax).
A lit-html template expression does not cause any DOM to be created or updated. It's only a description of DOM, called a
TemplateResult. To actually create or update DOM, you need to pass the
TemplateResult to the
render() function, along with a container to render to:
Render dynamic dataPermalink to “Render dynamic data”
To make your template dynamic, you can create a template function. Call the template function any time your data changes.
When you call the template function, lit-html captures the current expression values. The template function doesn't create any DOM nodes, so it's fast and cheap.
The template function returns a
TemplateResult that contains the template and the input data. This is one of the main principles behind using lit-html: creating UI as a function of state.
When you call
render, lit-html only updates the parts of the template that have changed since the last render. This makes lit-html updates very fast.
Render OptionsPermalink to “Render Options”
render method also takes an
options argument that allows you to specify the following options:
thisvalue to use when invoking event listeners registered with the
@eventNamesyntax. This option only applies when you specify an event listener as a plain function. If you specify the event listener using an event listener object, the listener object is used as the
thisvalue. See Event listener expressions for more on event listeners.
renderBefore: An optional reference node within the
containerbefore which lit-html will render. By default, lit-html will append to the end of the container. Setting
renderBeforeallows rendering to a specific spot within the container.
creationScope: The object lit-html will call
importNodeon when cloning templates (defaults to
document). This is provided for advanced use cases.
For example, if you're using
lit-html standalone, you might use render options like this:
The above example would render the template between the
Render options must be constant. Render options should not change between subsequent
Styles and lit-html templatesPermalink to “Styles and lit-html templates”
lit-html focuses on one thing: rendering HTML. How you apply styles to the HTML lit-html creates depends on how you're using it—for example, if you're using lit-html inside a component system like LitElement, you can follow the patterns used by that component system.
In general, how you style HTML will depend on whether you're using shadow DOM:
- If you are not rendering into shadow DOM, you can style HTML using global style sheets.
- If are rendering into shadow DOM, then you can render
<style>tags inside the shadow root.
Styling shadow roots on legacy browsers requires polyfills. Using the ShadyCSS polyfill with standalone
lit-html requires loading
lit-html/polyfill-support.js and passing a
scope option in
RenderOptions with the host tag name for scoping the rendered content. Although this approach is possible, we recommend using LitElement if you want to support rendering lit-html templates to shadow DOM on legacy browsers.
To help with dynamic styling, lit-html provides two directives for manipulating an element's
classMapsets classes on an element based on the properties of an object.
styleMapsets the styles on an element based on a map of style properties and values.