You're viewing docs for an older version of Lit. Click here for the latest version.

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

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

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.

render(props): unknown

Permalink to render View source
Parameters
props
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, props): unknown

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

Import

Methods and properties

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

Permalink to constructor
Parameters
element
MDN HTMLElement
name
string
strings
ReadonlyArray<string>
parent
Disconnectable
options
undefined | RenderOptions

readonly name: string

Permalink to name View source

readonly strings?: ReadonlyArray<string>

Permalink to strings View 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 | 5

Permalink to type View source

Import

Methods and properties

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

Permalink to constructor
Parameters
element
MDN HTMLElement
name
string
strings
ReadonlyArray<string>
parent
Disconnectable
options
undefined | RenderOptions

readonly name: string

Permalink to name View source

readonly strings?: ReadonlyArray<string>

Permalink to strings View source

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

Import

Methods and properties

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

Permalink to constructor
Parameters
startNode
ChildNode
endNode
null | ChildNode
parent
undefined | ChildPart | TemplateInstance
options
undefined | RenderOptions

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

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.

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

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

Import

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

Methods and properties

new Directive(_partInfo): Directive

Permalink to constructor
Parameters
_partInfo
PartInfo

render(props): unknown

Permalink to render View source
Parameters
props
Array<unknown>

update(_part, props): unknown

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

Import

Methods and properties

new ElementPart(element, parent, options): ElementPart

Permalink to constructor
Parameters
element
MDN Element
parent
Disconnectable
options
undefined | RenderOptions

Import

Methods and properties

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

Permalink to constructor
Parameters
element
MDN HTMLElement
name
string
strings
ReadonlyArray<string>
parent
Disconnectable
options
undefined | RenderOptions

readonly name: string

Permalink to name View source

readonly strings?: ReadonlyArray<string>

Permalink to strings View source

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

Parameters
event
Event

Import

Type

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

Import

Methods and properties

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

Permalink to constructor
Parameters
element
MDN HTMLElement
name
string
strings
ReadonlyArray<string>
parent
Disconnectable
options
undefined | RenderOptions

readonly name: string

Permalink to name View source

readonly strings?: ReadonlyArray<string>

Permalink to strings View source

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

Import

Methods and properties

readonly name: string

Permalink to name View source

readonly strings?: ReadonlyArray<string>

Permalink to strings View source

readonly tagName: string

Permalink to tagName View source

readonly type: 1 | 3 | 4 | 5

Permalink to type View source

Import

Methods and properties

Import

Methods and properties

Parameters
part
PartInfo

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

Type

Parameters<C["render"]>

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

Import

Import

Methods and properties

Import

Type

ChildPart | AttributePart | PropertyPart | BooleanAttributePart | ElementPart | EventPart

Information about the part a directive is bound to.

Import

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.

Import

Signature

clearPart(part): void

Parameters

part
ChildPart

Returns the committed value of a ChildPart.

Import

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

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

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

Signature

isDirectiveResult(value): value

Parameters

value
unknown

Tests if a value is a primitive value.

Import

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

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

Signature

isTemplateResult(value, type?): value

Parameters

value
unknown
type?
TemplateResultType

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

Import

Signature

removePart(part): void

Parameters

part
ChildPart

The Part to remove

Sets the value of a Part.

Import

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

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

Type

{HTML: 1, SVG: 2}

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

Import

Type

symbol