Skip to main content

Directives

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.

Import

Signature

asyncAppend(value, _mapper?): DirectiveResult<AsyncAppendDirective>

Parameters

value
AsyncIterable<unknown>

An async iterable

_mapper?
(v: unknown, index?: number) => unknown

Details

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.

AsyncAppendDirective

class View source

The type of the class that powers this directive. Necessary for naming the directive's return type.

Import

Methods and properties

new AsyncAppendDirective(partInfo): AsyncAppendDirective

Permalink to constructor
Parameters
partInfo
PartInfo

The connection state for this Directive.

commitValue(value, index): void

Permalink to commitValue View source
Parameters
value
unknown
index
number

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.

render(value, _mapper?): symbol

Permalink to render View source
Parameters
value
AsyncIterable<T>
_mapper?
Mapper<T>

Sets the value of the directive's Part outside the normal update/render lifecycle of a directive.

Parameters
value
unknown

The value to set

Details

This method should not be called synchronously from a directive's update or render.

update(part, params): undefined | noChange

Permalink to update View source
Parameters
part
ChildPart
params
[value, _mapper]

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.

Import

Signature

asyncReplace(value, _mapper?): DirectiveResult<AsyncReplaceDirective>

Parameters

value
AsyncIterable<unknown>

An async iterable

_mapper?
Mapper<unknown>

Details

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.

AsyncReplaceDirective

class View source

Import

Methods and properties

new AsyncReplaceDirective(_partInfo): AsyncReplaceDirective

Permalink to constructor
Parameters
_partInfo
PartInfo

The connection state for this Directive.

commitValue(value, _index): void

Permalink to commitValue View source
Parameters
value
unknown
_index
number

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.

render(value, _mapper?): symbol

Permalink to render View source
Parameters
value
AsyncIterable<T>
_mapper?
Mapper<T>

Sets the value of the directive's Part outside the normal update/render lifecycle of a directive.

Parameters
value
unknown

The value to set

Details

This method should not be called synchronously from a directive's update or render.

update(_part, __namedParameters): undefined | noChange

Permalink to update View source
Parameters
_part
ChildPart
__namedParameters
[value, _mapper]

Enables fast switching between multiple templates by caching the DOM nodes and TemplateInstances produced by the templates.

Import

Signature

cache(v): DirectiveResult<CacheDirective>

Parameters

v
unknown

Details

Example:

CacheDirective

class View source

The type of the class that powers this directive. Necessary for naming the directive's return type.

Import

Methods and properties

new CacheDirective(partInfo): CacheDirective

Permalink to constructor
Parameters
partInfo
PartInfo

render(v): Array<unknown>

Permalink to render View source
Parameters
v
unknown

update(containerPart, __namedParameters): Array<unknown>

Permalink to update View source
Parameters
containerPart
ChildPart
__namedParameters
[v]

A directive that applies dynamic CSS classes.

Import

Signature

classMap(classInfo): DirectiveResult<ClassMapDirective>

Parameters

classInfo
ClassInfo

Details

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.

ClassMapDirective

class View source

The type of the class that powers this directive. Necessary for naming the directive's return type.

Import

Methods and properties

new ClassMapDirective(partInfo): ClassMapDirective

Permalink to constructor
Parameters
partInfo
PartInfo

render(classInfo): string

Permalink to render View source
Parameters
classInfo
ClassInfo

update(part, __namedParameters): string | noChange

Permalink to update View source
Parameters
part
AttributePart
__namedParameters
[classInfo]

ClassInfo

type View source

A key-value set of class names to truthy values.

Import

Prevents re-render of a template function until a single value or an array of values changes.

Import

Signature

guard(_value, f): DirectiveResult<GuardDirective>

Parameters

_value
unknown
f
() => unknown

the template function

Details

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:

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:

In this case, items are mapped over only when the array reference changes.

GuardDirective

class View source

The type of the class that powers this directive. Necessary for naming the directive's return type.

Import

Methods and properties

new GuardDirective(_partInfo): GuardDirective

Permalink to constructor
Parameters
_partInfo
PartInfo

render(_value, f): unknown

Permalink to render View source
Parameters
_value
unknown
f
() => unknown

update(_part, __namedParameters): unknown

Permalink to update View source
Parameters
_part
Part
__namedParameters
[_value, f]

For AttributeParts, sets the attribute if the value is defined and removes the attribute if the value is undefined.

Import

Signature

ifDefined(value): nothing | NonNullable<T>

Parameters

value
T

Details

For other part types, this directive is a no-op.

Checks binding values against live DOM values, instead of previously bound values, when determining whether to update the value.

Import

Signature

live(value): DirectiveResult<LiveDirective>

Parameters

value
unknown

Details

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:

live() performs a strict equality check agains 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.

LiveDirective

class View source

The type of the class that powers this directive. Necessary for naming the directive's return type.

Import

Methods and properties

new LiveDirective(partInfo): LiveDirective

Permalink to constructor
Parameters
partInfo
PartInfo

render(value): unknown

Permalink to render View source
Parameters
value
unknown

update(part, __namedParameters): unknown

Permalink to update View source
Parameters
part
AttributePart
__namedParameters
[value]

Creates a new Ref object, which is container for a reference to an element.

Import

Signature

createRef(): Ref<T>

Sets the value of a Ref object or calls a ref callback with the element it's bound to.

Import

Signature

ref(_ref): DirectiveResult<RefDirective>

Parameters

_ref
RefOrCallback

Details

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).

Ref

class View source

An object that holds a ref value.

Import

Methods and properties

The current Element value of the ref, or else undefined if the ref is no longer rendered.

RefDirective

class View source

The type of the class that powers this directive. Necessary for naming the directive's return type.

Import

Methods and properties

new RefDirective(_partInfo): RefDirective

Permalink to constructor
Parameters
_partInfo
PartInfo

The connection state for this Directive.

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.

Parameters
_ref
RefOrCallback

Sets the value of the directive's Part outside the normal update/render lifecycle of a directive.

Parameters
value
unknown

The value to set

Details

This method should not be called synchronously from a directive's update or render.

update(part, __namedParameters): symbol

Permalink to update View source
Parameters
part
ElementPart
__namedParameters
[_ref]

RefOrCallback

type View source

Import

Type

Ref | (el: MDN Element | undefined) => void

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.

Import

Signature

repeat(items, keyFnOrTemplate, template?): unknown

Parameters

items
Iterable<T>
keyFnOrTemplate
KeyFn<T> | ItemTemplate<T>
template?
ItemTemplate<T>

Details

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.

RepeatDirective

class View source

The type of the class that powers this directive. Necessary for naming the directive's return type.

Import

Methods and properties

new RepeatDirective(partInfo): RepeatDirective

Permalink to constructor
Parameters
partInfo
PartInfo

render(items, template): Array<unknown>

Permalink to render View source
Parameters
items
Iterable<T>
template
ItemTemplate<T>

update(containerPart, __namedParameters): Array<unknown> | noChange

Permalink to update View source
Parameters
containerPart
ChildPart
__namedParameters
[Iterable<T>, KeyFn<T> | ItemTemplate<T>, ItemTemplate<T>]

ItemTemplate

type View source

Import

Type

(item: T, index: number) => unknown

KeyFn

type View source

Import

Type

(item: T, index: number) => unknown

RepeatDirectiveFn

type View source

Import

Signature

RepeatDirectiveFn(items, keyFnOrTemplate, template?): unknown

Parameters

items
Iterable<T>
keyFnOrTemplate
KeyFn<T> | ItemTemplate<T>
template?
ItemTemplate<T>

A directive that applies CSS properties to an element.

Import

Signature

styleMap(styleInfo): DirectiveResult<StyleMapDirective>

Parameters

styleInfo
StyleInfo

Details

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 property values as CSS properties. 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.

StyleMapDirective

class View source

The type of the class that powers this directive. Necessary for naming the directive's return type.

Import

Methods and properties

new StyleMapDirective(partInfo): StyleMapDirective

Permalink to constructor
Parameters
partInfo
PartInfo

render(styleInfo): string

Permalink to render View source
Parameters
styleInfo
StyleInfo

update(part, __namedParameters): string | noChange

Permalink to update View source
Parameters
part
AttributePart
__namedParameters
[styleInfo]

StyleInfo

type View source

A key-value set of CSS properties and values.

Import

Details

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.

Renders the content of a template element as HTML.

Import

Signature

templateContent(template): DirectiveResult<TemplateContentDirective>

Parameters

template
MDN HTMLTemplateElement

Details

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.

TemplateContentDirective

class View source

The type of the class that powers this directive. Necessary for naming the directive's return type.

Import

Methods and properties

new TemplateContentDirective(partInfo): TemplateContentDirective

Permalink to constructor
Parameters
partInfo
PartInfo
Parameters
template
MDN HTMLTemplateElement

update(_part, props): unknown

Permalink to update View source
Parameters
_part
Part
props
Array<unknown>

Renders the result as HTML, rather than text.

Import

Signature

unsafeHTML(value): DirectiveResult<UnsafeHTMLDirective>

Parameters

value
undefined | null | string | noChange | nothing

Details

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.

UnsafeHTMLDirective

class View source

Import

Methods and properties

new UnsafeHTMLDirective(partInfo): UnsafeHTMLDirective

Permalink to constructor
Parameters
partInfo
PartInfo

static directiveName: string

Permalink to directiveName View source

static resultType: number

Permalink to resultType View source

render(value): undefined | null | noChange | nothing | TemplateResult<1 | 2>

Permalink to render View source
Parameters
value
undefined | null | string | noChange | nothing

update(_part, props): unknown

Permalink to update View source
Parameters
_part
Part
props
Array<unknown>

Renders the result as SVG, rather than text.

Import

Signature

unsafeSVG(value): DirectiveResult<UnsafeSVGDirective>

Parameters

value
undefined | null | string | noChange | nothing

Details

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.

UnsafeSVGDirective

class View source

The type of the class that powers this directive. Necessary for naming the directive's return type.

Import

Methods and properties

new UnsafeSVGDirective(partInfo): UnsafeSVGDirective

Permalink to constructor
Parameters
partInfo
PartInfo

static directiveName: string

Permalink to directiveName View source

static resultType: number

Permalink to resultType View source

render(value): undefined | null | noChange | nothing | TemplateResult<1 | 2>

Permalink to render View source
Parameters
value
undefined | null | string | noChange | nothing

update(_part, props): unknown

Permalink to update View source
Parameters
_part
Part
props
Array<unknown>

Renders one of a series of values, including Promises, to a Part.

Import

Signature

until(values): DirectiveResult<UntilDirective>

Parameters

values
Array<unknown>

Details

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:

UntilDirective

class View source

Import

Methods and properties

new UntilDirective(_partInfo): UntilDirective

Permalink to constructor
Parameters
_partInfo
PartInfo

The connection state for this Directive.

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.

Parameters
args
Array<unknown>

Sets the value of the directive's Part outside the normal update/render lifecycle of a directive.

Parameters
value
unknown

The value to set

Details

This method should not be called synchronously from a directive's update or render.

update(_part, args): unknown

Permalink to update View source
Parameters
_part
Part
args
Array<unknown>