Custom directives

class AsyncDirectiveSource

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

Import

import { AsyncDirective } from 'lit/async-directive.js';

Details

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.

Methods and properties

new AsyncDirective(_partInfo): AsyncDirective

Parameters

_partInfo: PartInfo

isConnected: booleanSource

The connection state for this Directive.

disconnected(): voidSource

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.

reconnected(): voidSource

render(props): unknownSource

Parameters

props: Array<unknown>

setValue(value): voidSource

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, props): unknownSource

Parameters

_part: Part
props: Array<unknown>

class AttributePartSource

Import

import { AttributePart } from 'lit/async-directive.js';

Methods and properties

new AttributePart(element, name, strings, parent, options): AttributePart

Parameters

element: HTMLElement
name: string
strings: ReadonlyArray<string>
parent: Disconnectable
options: undefined | RenderOptions

readonly element: HTMLElementSource

readonly name: stringSource

readonly options: undefined | RenderOptionsSource

readonly strings?: ReadonlyArray<string>Source

If this attribute part represents an interpolation, this contains the static strings of the interpolation. For single-value, complete bindings, this is undefined.

readonly type: 1 | 3 | 4 | 5Source

tagName: stringSource

class BooleanAttributePartSource

Import

import { BooleanAttributePart } from 'lit/async-directive.js';

Methods and properties

new BooleanAttributePart(element, name, strings, parent, options): BooleanAttributePart

Parameters

element: HTMLElement
name: string
strings: ReadonlyArray<string>
parent: Disconnectable
options: undefined | RenderOptions

readonly element: HTMLElementSource

readonly name: stringSource

readonly options: undefined | RenderOptionsSource

readonly strings?: ReadonlyArray<string>Source

If this attribute part represents an interpolation, this contains the static strings of the interpolation. For single-value, complete bindings, this is undefined.

readonly type: 4Source

tagName: stringSource

class ChildPartSource

Import

import { ChildPart } from 'lit/async-directive.js';

Methods and properties

new ChildPart(startNode, endNode, parent, options): ChildPart

Parameters

startNode: ChildNode
endNode: null | ChildNode
parent: undefined | ChildPart | TemplateInstance
options: undefined | RenderOptions

readonly options: undefined | RenderOptionsSource

readonly type: 2Source

endNode: null | NodeSource

The part's trailing marker node, if any. See .parentNode for more information.

parentNode: NodeSource

The parent node into which the part renders its content.

Details

A ChildPart's content consists of a range of adjacent child nodes of .parentNode, possibly bordered by 'marker nodes' (.startNode and .endNode).

If both .startNode and .endNode are non-null, then the part's content consists of all siblings between .startNode and .endNode, exclusively.
If .startNode is non-null but .endNode is null, then the part's content consists of all siblings following .startNode, up to and including the last child of .parentNode. If .endNode is non-null, then .startNode will always be non-null.
If both .endNode and .startNode are null, then the part's content consists of all child nodes of .parentNode.

startNode: null | NodeSource

The part's leading marker node, if any. See .parentNode for more information.

function directiveSource

Creates a user-facing directive function from a Directive class. This function has the same parameters as the directive's render() method.

Import

import { directive } from 'lit/async-directive.js';

Signature

directive(c): (values: Parameters<InstanceType<C>["render"]>) => DirectiveResult<C>

Parameters

c: C

class DirectiveSource

Base class for creating custom directives. Users should extend this class, implement render and/or update, and then pass their subclass to directive.

Import

import { Directive } from 'lit/async-directive.js';

Methods and properties

new Directive(_partInfo): Directive

Parameters

_partInfo: PartInfo

render(props): unknownSource

Parameters

props: Array<unknown>

update(_part, props): unknownSource

Parameters

_part: Part
props: Array<unknown>

class ElementPartSource

Import

import { ElementPart } from 'lit/async-directive.js';

Methods and properties

new ElementPart(element, parent, options): ElementPart

Parameters

element: Element
parent: Disconnectable
options: undefined | RenderOptions

element: ElementSource

options: undefined | RenderOptionsSource

readonly type: 6Source

class EventPartSource

Import

import { EventPart } from 'lit/async-directive.js';

Methods and properties

new EventPart(element, name, strings, parent, options): EventPart

Parameters

element: HTMLElement
name: string
strings: ReadonlyArray<string>
parent: Disconnectable
options: undefined | RenderOptions

readonly element: HTMLElementSource

readonly name: stringSource

readonly options: undefined | RenderOptionsSource

readonly strings?: ReadonlyArray<string>Source

If this attribute part represents an interpolation, this contains the static strings of the interpolation. For single-value, complete bindings, this is undefined.

readonly type: 5Source

tagName: stringSource

handleEvent(event): voidSource

Parameters

event: Event

value PartTypeSource

Import

import { PartType } from 'lit/async-directive.js';

Type

{ATTRIBUTE: 1, BOOLEAN_ATTRIBUTE: 4, CHILD: 2, ELEMENT: 6, EVENT: 5, PROPERTY: 3}

class PropertyPartSource

Import

import { PropertyPart } from 'lit/async-directive.js';

Methods and properties

new PropertyPart(element, name, strings, parent, options): PropertyPart

Parameters

element: HTMLElement
name: string
strings: ReadonlyArray<string>
parent: Disconnectable
options: undefined | RenderOptions

readonly element: HTMLElementSource

readonly name: stringSource

readonly options: undefined | RenderOptionsSource

readonly strings?: ReadonlyArray<string>Source

If this attribute part represents an interpolation, this contains the static strings of the interpolation. For single-value, complete bindings, this is undefined.

readonly type: 3Source

tagName: stringSource

type AttributePartInfoSource

Import

import { AttributePartInfo } from 'lit/async-directive.js';

Methods and properties

readonly name: stringSource

readonly strings?: ReadonlyArray<string>Source

readonly tagName: stringSource

readonly type: 1 | 3 | 4 | 5Source

type ChildPartInfoSource

Import

import { ChildPartInfo } from 'lit/async-directive.js';

Methods and properties

readonly type: 2Source

type DirectiveClassSource

Import

import { DirectiveClass } from 'lit/async-directive.js';

Methods and properties

new Directive(part): DirectiveSource

Parameters

part: PartInfo

type DirectiveParametersSource

This utility type extracts the signature of a directive class's render() method so we can use it for the type of the generated directive function.

Import

import { DirectiveParameters } from 'lit/async-directive.js';

Type

Parameters<C["render"]>

type DirectiveResultSource

A generated directive function doesn't evaluate the directive, but just returns a DirectiveResult object that captures the arguments.

Import

import { DirectiveResult } from 'lit/async-directive.js';

type ElementPartInfoSource

Import

import { ElementPartInfo } from 'lit/async-directive.js';

Methods and properties

readonly type: 6Source

type PartSource

Import

import { Part } from 'lit/async-directive.js';

Type

type PartInfoSource

Information about the part a directive is bound to.

Import

import { PartInfo } from 'lit/async-directive.js';

Type

ChildPartInfo | AttributePartInfo | ElementPartInfo

Details

This is useful for checking that a directive is attached to a valid part, such as with directive that can only be used on attribute bindings.

function clearPartSource

Import

import { clearPart } from 'lit/directive-helpers.js';

Signature

clearPart(part): void

Parameters

part: ChildPart

function getCommittedValueSource

Returns the committed value of a ChildPart.

Import

import { getCommittedValue } from 'lit/directive-helpers.js';

Signature

getCommittedValue(part): unknown

Parameters

part: ChildPart

Details

The committed value is used for change detection and efficient updates of the part. It can differ from the value set by the template or directive in cases where the template value is transformed before being committed.

TemplateResults are committed as a TemplateInstance
Iterables are committed as Array<ChildPart>
All other types are committed as the template value or value returned or set by a directive.

function getDirectiveClassSource

Retrieves the Directive class for a DirectiveResult

Import

import { getDirectiveClass } from 'lit/directive-helpers.js';

Signature

getDirectiveClass(value): undefined | DirectiveClass

Parameters

value: unknown

function insertPartSource

Inserts a ChildPart into the given container ChildPart's DOM, either at the end of the container ChildPart, or before the optional refPart.

Import

import { insertPart } from 'lit/directive-helpers.js';

Signature

insertPart(containerPart, refPart?, part?): ChildPart

Parameters

containerPart: ChildPart
Part within which to add the new ChildPart
refPart?: ChildPart
Part before which to add the new ChildPart; when omitted the part added to the end of the containerPart
part?: ChildPart
Part to insert, or undefined to create a new part

Details

This does not add the part to the containerPart's committed value. That must be done by callers.

function isDirectiveResultSource

Tests if a value is a DirectiveResult.

Import

import { isDirectiveResult } from 'lit/directive-helpers.js';

Signature

isDirectiveResult(value): value

Parameters

value: unknown

function isPrimitiveSource

Tests if a value is a primitive value.

Import

import { isPrimitive } from 'lit/directive-helpers.js';

Signature

isPrimitive(value): value

Parameters

value: unknown

Details

See https://tc39.github.io/ecma262/#sec-typeof-operator

function isSingleExpressionSource

Tests whether a part has only a single-expression with no strings to interpolate between.

Import

import { isSingleExpression } from 'lit/directive-helpers.js';

Signature

isSingleExpression(part): boolean

Parameters

part: PartInfo

Details

Only AttributePart and PropertyPart can have multiple expressions. Multi-expression parts have a strings property and single-expression parts do not.

function isTemplateResultSource

Tests if a value is a TemplateResult.

Import

import { isTemplateResult } from 'lit/directive-helpers.js';

Signature

isTemplateResult(value, type?): value

Parameters

value: unknown
type?: TemplateResultType

function removePartSource

Removes a ChildPart from the DOM, including any of its content.

Import

import { removePart } from 'lit/directive-helpers.js';

Signature

removePart(part): void

Parameters

part: ChildPart
The Part to remove

function setChildPartValueSource

Sets the value of a Part.

Import

import { setChildPartValue } from 'lit/directive-helpers.js';

Signature

setChildPartValue(part, value, directiveParent?): T

Parameters

part: T
Part to set
value: unknown
Value to set
directiveParent?: DirectiveParent
Used internally; should not be set by user

Details

Note that this should only be used to set/update the value of user-created parts (i.e. those created using insertPart); it should not be used by directives to set the value of the directive's container part. Directives should return a value from update/render to update their part state. For directives that require setting their part value asynchronously, they should extend AsyncDirective and call this.setValue().

function setCommittedValueSource

Sets the committed value of a ChildPart directly without triggering the commit stage of the part.

Import

import { setCommittedValue } from 'lit/directive-helpers.js';

Signature

setCommittedValue(part, value?): unknown

Parameters

part: Part
value?: unknown

Details

This is useful in cases where a directive needs to update the part such that the next update detects a value change or not. When value is omitted, the next update will be guaranteed to be detected as a change.

value TemplateResultTypeSource

Import

import { TemplateResultType } from 'lit/directive-helpers.js';

Type

{HTML: 1, SVG: 2}

value noChangeSource

A sentinel value that signals that a value was handled by a directive and should not be written to the DOM.

Import

import { noChange } from 'lit';

Type

symbol