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 aren't using shadow DOM, you can style HTML using global style sheets.
- If you're using shadow DOM (for example, in LitElement), then you can add style sheets inside the shadow root.
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.
Setting classes with classMapPermalink to “Setting classes with classMap”
classMap directive lets you set a group of classes based on an object.
More information: see classMap in the Template syntax reference.
Inline styles with styleMapPermalink to “Inline styles with styleMap”
You can use the
styleMap directive to set inline styles on an element in the template.
More information: see styleMap in the Template syntax reference.
Rendering in shadow DOMPermalink to “Rendering in shadow DOM”
When rendering into a shadow root, you usually want to add a style sheet inside the shadow root to the template, so you can style the contents of the shadow root.
This pattern may seem inefficient, since the same style sheet is reproduced in each instance of an element. However, the browser can deduplicate multiple instances of the same style sheet, so the cost of parsing the style sheet is only paid once.
A new feature available in some browsers is Constructable Stylesheets Objects. This proposed standard allows multiple shadow roots to explicitly share style sheets. LitElement uses this feature in its static
Bindings in style sheetsPermalink to “Bindings in style sheets”
Binding to values in the style sheet is an antipattern, because it defeats the browser's style sheet optimizations. It's also not supported by the ShadyCSS polyfill.
Alternatives to using bindings in a style sheet:
- Use CSS custom properties to pass values down the tree.
- Use bindings in the
styleattributes to control the styling of child elements.
Polyfilled shadow DOM: ShadyDOM and ShadyCSSPermalink to “Polyfilled shadow DOM: ShadyDOM and ShadyCSS”
If you're using shadow DOM, you'll probably need to use polyfills to support older browsers that don't implement shadow DOM natively. ShadyDOM and ShadyCSS are polyfills, or shims, that emulate shadow DOM isolation and style scoping.
shady-render module provides necessary integration with the shady CSS shim. If you're writing your own custom element base class that uses lit-html and shadow DOM, you'll need to use
shady-render and also take some steps on your own.
The ShadyCSS README provides some directions for using shady CSS. When using it with
You don't need to call
ShadyCSS.prepareTemplate. Instead pass the scope name as a render option. For custom elements, use the element name as a scope name. For example:
this.myTemplateis a method that returns a
You do need to call
ShadyCSS.styleElementwhen the element is connected to the DOM, and in case of any dynamic changes that might affect custom property values.
For example, consider a set of rules like this:
If you add an instance of
my-elementto a document, or move it, a different value of
--theme-colormay apply. On browsers with native custom property support, these changes will take place automatically, but on browsers that rely on the custom property shim included with shadyCSS, you'll need to call