Add a template to your component to define what it should render. Templates can include expressions, which are placeholders for dynamic content.
To define a template for a Lit component, add a
html tag function.
Renderable valuesPermalink to “Renderable values”
Typically, the component's
render() method returns a single
TemplateResult object (the same type returned by the
html tag function). However, it can return anything that Lit can render as the child of an HTML element:
- Primitive values like string, number, or boolean.
TemplateResultobjects created by the
- DOM Nodes.
- The sentinel values
- Arrays or iterables of any of the supported types.
This is almost identical to the set of values that can be rendered to a Lit child expression. The one difference is that a child expression can render an
SVGTemplateResult, returned by the
svg function. This kind of template result can only be rendered as the descendant of an
Writing a good render() methodPermalink to “Writing a good render() method”
To take best advantage of Lit's functional rendering model, your
render() method should follow these guidelines:
- Avoid changing the component's state.
- Avoid producing any side effects.
- Use only the component's properties as input.
- Return the same result when given the same property values.
Following these guidelines keeps the template deterministic, and makes it easier to reason about the code.
In most cases you should avoid making DOM updates outside of
render(). Instead, express the component's template as a function of its state, and capture its state in properties.
For example, if your component needs to update its UI when it receives an event, have the event listener set a reactive property that is used in
render(), rather than manipulate the DOM directly.
For more information, see Reactive properties.
Composing templatesPermalink to “Composing templates”
You can compose Lit templates from other templates. The following example composes a template for a component called
<my-page> from smaller templates for the page's header, footer, and main content:
In this example, the individual templates are defined as instance methods, so a subclass could extend this component and override one or more templates.
Move example to composition section, add xref.
You can also compose templates by importing other elements and using them in your template:
When templates renderPermalink to “When templates render”
A Lit component renders its template initially when it's added to the DOM on a page. After the initial render, any change to the component's reactive properties triggers an update cycle, re-rendering the component.
Lit batches updates to maximize performance and efficiency. Setting multiple properties at once triggers only one update, performed asynchronously at microtask timing.
During an update, only the parts of the DOM that change are re-rendered. Although Lit templates look like string interpolation, Lit parses and creates static HTML once, and then only updates changed values in expressions after that, making updates very efficient.
For more information about the update cycle, see What happens when properties change.
DOM encapsulationPermalink to “DOM encapsulation”
Lit uses shadow DOM to encapsulate the DOM a component renders. Shadow DOM lets an element create its own, isolated DOM tree that's separate from the main document tree. It's a core feature of the web components specifications that enables interoperability, style encapsulation, and other benefits.
For more information about shadow DOM, see Shadow DOM v1: Self-Contained Web Components on Web Fundamentals.
For more information about working with shadow DOM in your component, see Working with shadow DOM.