Skip to main content

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.setDirectiveConnection(false) on a part that was previously rendered containing the directive.

Import

Details

If part.setDirectiveConnection(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.

Methods and properties

new AsyncDirective(_partInfo): AsyncDirective

Permalink to constructor
Parameters
_partInfo
PartInfo

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.

If the method is called while the part is disconnected, the value will be queued until directive is reconnected.

update(_part, props): unknown

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

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

Import

Signature

clearPart(part): void

Parameters

part
Interface<ChildPartImpl>

Returns the committed value of a ChildPart.

Import

Signature

getCommittedValue(part): unknown

Parameters

part
Interface<ChildPartImpl>

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

  • 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?): Interface<ChildPartImpl>

Parameters

containerPart
Interface<ChildPartImpl>

Part within which to add the new ChildPart

refPart?
{_$clear: (start?: null | ChildNode, from?: number) => void, _$committedValue: unknown, _$disconnetableChildren: Set<Disconnectable>, _$endNode: null | ChildNode, _$getTemplate: (result: TemplateResult<1 | 2>) => Template, _$parent: undefined | Disconnectable, _$reparentDisconnectables: (parent: Disconnectable) => void, _$setChildPartConnected: (isConnected: boolean, removeFromParent?: boolean, from?: number) => void, _$setValue: (value: unknown, directiveParent?: DirectiveParent) => void, _$startNode: ChildNode, __directive: Directive, endNode: null | Node, options: undefined | RenderOptions, parentNode: Node, setConnected: (isConnected: boolean) => void, startNode: null | Node, type: 2}

Part before which to add the new ChildPart; when omitted the part added to the end of the containerPart

part?
{_$clear: (start?: null | ChildNode, from?: number) => void, _$committedValue: unknown, _$disconnetableChildren: Set<Disconnectable>, _$endNode: null | ChildNode, _$getTemplate: (result: TemplateResult<1 | 2>) => Template, _$parent: undefined | Disconnectable, _$reparentDisconnectables: (parent: Disconnectable) => void, _$setChildPartConnected: (isConnected: boolean, removeFromParent?: boolean, from?: number) => void, _$setValue: (value: unknown, directiveParent?: DirectiveParent) => void, _$startNode: ChildNode, __directive: Directive, endNode: null | Node, options: undefined | RenderOptions, parentNode: Node, setConnected: (isConnected: boolean) => void, startNode: null | Node, type: 2}

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?
1 | 2

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

Import

Signature

removePart(part): void

Parameters

part
Interface<ChildPartImpl>

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}

directive

reference Permalink to directive

Import

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

Type

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

Import

Type

Interface<AttributePartImpl>

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

Type

Interface<BooleanAttributePartImpl>

Import

Type

Interface<ChildPartImpl>

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

Methods and properties

values: Parameters<InstanceType<C>["render"]>

Permalink to values View source

Import

Type

Interface<ElementPartImpl>

Import

Methods and properties

An AttributePart that manages an event listener via add/removeEventListener.

Import

Type

Interface<EventPartImpl>

Details

This part works by adding itself as the event listener on an element, then delegating to the value passed to it. This reduces the number of calls to add/removeEventListener if the listener changes frequently, such as when an inline function is used as a listener.

Because event options are passed when adding listeners, we must take case to add and remove the part as a listener when the event options change.

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.

AttributePart

reference Permalink to AttributePart

Import

BooleanAttributePart

reference Permalink to BooleanAttributePart

Import

ChildPart

reference Permalink to ChildPart

Import

ElementPart

reference Permalink to ElementPart

Import

EventPart

reference Permalink to EventPart

Import

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

Import

Type

symbol

Part

reference Permalink to Part

Import

Import

Type

Interface<PropertyPartImpl>