A directive that renders the items of an async iterable[1], appending new values after previous values, similar to the built-in support for iterables. This directive is usable only in child expressions.
Async iterables are objects with a [Symbol.asyncIterator] method, which returns an iterator who's next() method returns a Promise. When a new value is available, the Promise resolves and the value is appended to the Part controlled by the directive. If another value other than this directive has been set on the Part, the iterable will no longer be listened to and new values won't be written to the Part. [1]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of
An abstract Directive base class whose disconnected method will be called when the part containing the directive is cleared as a result of re-rendering, or when the user calls part.setConnected(false) on a part that was previously rendered containing the directive (as happens when e.g. a LitElement disconnects from the DOM).
If part.setConnected(true) is subsequently called on a containing part, the directive's reconnected method will be called prior to its next update/render callbacks. When implementing disconnected, reconnected should also be implemented to be compatible with reconnection. Note that updates may occur while the directive is disconnected. As such, directives should generally check the this.isConnected flag during render/update to determine whether it is safe to subscribe to resources that may prevent garbage collection.
User callbacks for implementing logic to release any resources/subscriptions that may have been retained by this directive. Since directives may also be re-connected, reconnected should also be implemented to restore the working state of the directive prior to the next render.
A directive that renders the items of an async iterable[1], replacing previous values with new values, so that only one value is ever rendered at a time. This directive may be used in any expression type.
Async iterables are objects with a [Symbol.asyncIterator] method, which returns an iterator who's next() method returns a Promise. When a new value is available, the Promise resolves and the value is rendered to the Part controlled by the directive. If another value other than this directive has been set on the Part, the iterable will no longer be listened to and new values won't be written to the Part. [1]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of
An abstract Directive base class whose disconnected method will be called when the part containing the directive is cleared as a result of re-rendering, or when the user calls part.setConnected(false) on a part that was previously rendered containing the directive (as happens when e.g. a LitElement disconnects from the DOM).
If part.setConnected(true) is subsequently called on a containing part, the directive's reconnected method will be called prior to its next update/render callbacks. When implementing disconnected, reconnected should also be implemented to be compatible with reconnection. Note that updates may occur while the directive is disconnected. As such, directives should generally check the this.isConnected flag during render/update to determine whether it is safe to subscribe to resources that may prevent garbage collection.
User callbacks for implementing logic to release any resources/subscriptions that may have been retained by this directive. Since directives may also be re-connected, reconnected should also be implemented to restore the working state of the directive prior to the next render.
Chooses and evaluates a template function from a list based on matching the given value to a case.
Import
import { choose } from'lit/directives/choose.js';
Signature
choose(value, cases, defaultCase?): undefined | V
Parameters
value
T
cases
Array<[T, () => V]>
defaultCase?
() => V
Details
Cases are structured as [caseValue, func]. value is matched to caseValue by strict equality. The first match is selected. Case values can be of any type including primitives, objects, and symbols. This is similar to a switch statement, but as an expression and without fallthrough.
This must be used in the class attribute and must be the only part used in the attribute. It takes each property in the classInfo argument and adds the property name to the element's classList if the property value is truthy; if the property value is falsey, the property name is removed from the element's class. For example {foo: bar} applies the class foo if the value of bar is truthy.
Values are checked against previous values with strict equality (===), and so the check won't detect nested property changes inside objects or arrays. Arrays values have each item checked against the previous value at the same index with strict equality. Nested arrays are also checked only by strict equality. Example:
html`
<div>
${guard([user.id, company.id], () =>html`...`)}
</div>
`
In this case, the template only rerenders if either user.id or company.id changes. guard() is useful with immutable data patterns, by preventing expensive work until data updates. Example:
Associates a renderable value with a unique key. When the key changes, the previous DOM is removed and disposed before rendering the next value, even if the value - such as a template - is the same.
This is useful for forcing re-renders of stateful components, or working with code that expects new data to generate new HTML elements, such as some animation techniques.
This is useful for cases where the DOM value may change from outside of lit-html, such as with a binding to an <input> element's value property, a content editable elements text, or to a custom element that changes it's own properties or attributes. In these cases if the DOM value changes, but the value set through lit-html bindings hasn't, lit-html won't know to update the DOM value and will leave it alone. If this is not what you want--if you want to overwrite the DOM value with the bound value no matter what--use the live() directive:
html`<input.value=${live(x)}>`
live() performs a strict equality check against the live DOM value, and if the new value is equal to the live value, does nothing. This means that live() should not be used when the binding will cause a type conversion. If you use live() with an attribute binding, make sure that only strings are passed in, or the binding will update every render.
A Ref object acts as a container for a reference to an element. A ref callback is a function that takes an element as its only argument. The ref directive sets the value of the Ref object or calls the ref callback during rendering, if the referenced element changed. Note: If a ref callback is rendered to a different element position or is removed in a subsequent render, it will first be called with undefined, followed by another call with the new element it was rendered to (if any).
An abstract Directive base class whose disconnected method will be called when the part containing the directive is cleared as a result of re-rendering, or when the user calls part.setConnected(false) on a part that was previously rendered containing the directive (as happens when e.g. a LitElement disconnects from the DOM).
If part.setConnected(true) is subsequently called on a containing part, the directive's reconnected method will be called prior to its next update/render callbacks. When implementing disconnected, reconnected should also be implemented to be compatible with reconnection. Note that updates may occur while the directive is disconnected. As such, directives should generally check the this.isConnected flag during render/update to determine whether it is safe to subscribe to resources that may prevent garbage collection.
User callbacks for implementing logic to release any resources/subscriptions that may have been retained by this directive. Since directives may also be re-connected, reconnected should also be implemented to restore the working state of the directive prior to the next render.
A directive that repeats a series of values (usually TemplateResults) generated from an iterable, and updates those items efficiently when the iterable changes based on user-provided keys associated with each item.
Note that if a keyFn is provided, strict key-to-DOM mapping is maintained, meaning previous DOM for a given key is moved into the new position if needed, and DOM will never be reused with values for different keys (new DOM will always be created for new keys). This is generally the most efficient way to use repeat since it performs minimum unnecessary work for insertions and removals. The keyFn takes two parameters, the item and its index, and returns a unique key value.
Important: If providing a keyFn, keys must be unique for all items in a given call to repeat. The behavior when two or more items have the same key is undefined. If no keyFn is provided, this directive will perform similar to mapping items to values, and DOM will be reused against potentially different items.
styleMap can only be used in the style attribute and must be the only expression in the attribute. It takes the property names in the styleInfo object and adds the properties to the inline style of the element. Property names with dashes (-) are assumed to be valid CSS property names and set on the element's style object using setProperty(). Names without dashes are assumed to be camelCased JavaScript property names and set on the element's style object using property assignment, allowing the style object to translate JavaScript-style names to CSS property names. For example styleMap({backgroundColor: 'red', 'border-top': '5px', '--size': '0'}) sets the background-color, border-top and --size properties.
The key should be either a valid CSS property name string, like 'background-color', or a valid JavaScript camel case property name for CSSStyleDeclaration like backgroundColor.
Note, the template should be developer controlled and not user controlled. Rendering a user-controlled template with this directive could lead to cross-site-scripting vulnerabilities.
The values undefined, null, and nothing, will all result in no content (empty string) being rendered. Note, this is unsafe to use with any user-provided input that hasn't been sanitized or escaped, as it may lead to cross-site-scripting vulnerabilities.
The values undefined, null, and nothing, will all result in no content (empty string) being rendered. Note, this is unsafe to use with any user-provided input that hasn't been sanitized or escaped, as it may lead to cross-site-scripting vulnerabilities.
Values are rendered in priority order, with the first argument having the highest priority and the last argument having the lowest priority. If a value is a Promise, low-priority values will be rendered until it resolves. The priority of values can be used to create placeholder content for async data. For example, a Promise with pending content can be the first, highest-priority, argument, and a non_promise loading indicator template can be used as the second, lower-priority, argument. The loading indicator will render immediately, and the primary content will render when the Promise resolves. Example:
An abstract Directive base class whose disconnected method will be called when the part containing the directive is cleared as a result of re-rendering, or when the user calls part.setConnected(false) on a part that was previously rendered containing the directive (as happens when e.g. a LitElement disconnects from the DOM).
If part.setConnected(true) is subsequently called on a containing part, the directive's reconnected method will be called prior to its next update/render callbacks. When implementing disconnected, reconnected should also be implemented to be compatible with reconnection. Note that updates may occur while the directive is disconnected. As such, directives should generally check the this.isConnected flag during render/update to determine whether it is safe to subscribe to resources that may prevent garbage collection.
User callbacks for implementing logic to release any resources/subscriptions that may have been retained by this directive. Since directives may also be re-connected, reconnected should also be implemented to restore the working state of the directive prior to the next render.