Custom directives

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.

Import

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

Import

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

Import

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

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

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';

Import

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

Import

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

Import

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

Type

Import

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

Import

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

Import

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

Import

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

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

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';

Import

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

Import

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

Type

Information about the part a directive is bound to.

Import

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

Type

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.

Import

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

Signature

clearPart(part): void

Parameters

part

ChildPart

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.

Retrieves the Directive class for a DirectiveResult

Import

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

Signature

getDirectiveClass(value): undefined | DirectiveClass

Parameters

value

unknown

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.

Tests if a value is a DirectiveResult.

Import

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

Signature

isDirectiveResult(value): value

Parameters

value

unknown

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

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.

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

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

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

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.

Import

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

Type

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