Custom directives

class AttributeCommitterSource

Writes attribute values to the DOM for a group of AttributeParts bound to a single attribute. The value is only set once even if there are multiple parts for an attribute.

Import

import { AttributeCommitter } from 'lit-html';

Methods and properties

new AttributeCommitter(element, name, strings): AttributeCommitterSource

Parameters

element: Element
name: string
strings: ReadonlyArray<string>

dirty: booleanSource

readonly element: ElementSource

readonly name: stringSource

readonly parts: ReadonlyArray<AttributePart>Source

readonly strings: ReadonlyArray<string>Source

commit(): voidSource

class AttributePartSource

A Part that controls all or part of an attribute value.

Import

import { AttributePart } from 'lit-html';

Methods and properties

new AttributePart(committer): AttributePartSource

Parameters

committer: AttributeCommitter

readonly committer: AttributeCommitterSource

value: unknownSource

commit(): voidSource

Commits the current part value, causing it to actually be written to the DOM.

Details

Directives are run at the start of commit, so that if they call part.setValue(...) synchronously that value will be used in the current commit, and there's no need to call part.commit() within the directive. If directives set a part value asynchronously, then they must call part.commit() manually.

setValue(value): voidSource

Sets the current part value, but does not write it to the DOM.

Parameters

value: unknown

class BooleanAttributePartSource

Implements a boolean attribute, roughly as defined in the HTML specification.

Import

import { BooleanAttributePart } from 'lit-html';

Details

If the value is truthy, then the attribute is present with a value of ''. If the value is falsey, the attribute is removed.

Methods and properties

new BooleanAttributePart(element, name, strings): BooleanAttributePartSource

Parameters

element: Element
name: string
strings: ReadonlyArray<string>

readonly element: ElementSource

readonly name: stringSource

readonly strings: ReadonlyArray<string>Source

value: unknownSource

commit(): voidSource

Commits the current part value, causing it to actually be written to the DOM.

Details

setValue(value): voidSource

Sets the current part value, but does not write it to the DOM.

Parameters

value: unknown

function createMarkerSource

Import

import { createMarker } from 'lit-html';

Signature

createMarker(): Comment

value defaultTemplateProcessorSource

Import

import { defaultTemplateProcessor } from 'lit-html';

Type

DefaultTemplateProcessor

class DefaultTemplateProcessorSource

Creates Parts when a template is instantiated.

Import

import { DefaultTemplateProcessor } from 'lit-html';

Methods and properties

new DefaultTemplateProcessor(): DefaultTemplateProcessor

handleAttributeExpressions(element, name, strings, options): ReadonlyArray<Part>Source

Create parts for an attribute-position binding, given the event, attribute name, and string literals.

Parameters

element: Element
The element containing the binding
name: string
The attribute name
strings: Array<string>
The string literals. There are always at least two strings, event for fully-controlled bindings with a single expression.
options: RenderOptions

handleTextExpression(options): NodePartSource

Create parts for a text-position binding.

Parameters

options: RenderOptions

function directiveSource

Brands a function as a directive factory function so that lit-html will call the function during template rendering, rather than passing as a value.

Import

import { directive } from 'lit-html';

Signature

directive(f): F

Parameters

f: F
The directive factory function. Must be a function that returns a function of the signature (part: Part) => void. The returned function will be called with the part object.

Details

A directive is a function that takes a Part as an argument. It has the signature: (part: Part) => void.

A directive factory is a function that takes arguments for data and configuration and returns a directive. Users of directive usually refer to the directive factory as the directive. For example, "The repeat directive".

Usually a template author will invoke a directive factory in their template with relevant arguments, which will then return a directive function.

Here's an example of using the repeat() directive factory that takes an array and a function to render an item:

html`<ul><${repeat(items, (item) => html`<li>${item}</li>`)}</ul>`

When repeat is invoked, it returns a directive function that closes over items and the template function. When the outer template is rendered, the return directive function is called with the Part for the expression. repeat then performs it's custom logic to render multiple items.

class EventPartSource

Import

import { EventPart } from 'lit-html';

Methods and properties

new EventPart(element, eventName, eventContext?): EventPartSource

Parameters

element: Element
eventName: string
eventContext?: EventTarget

readonly element: ElementSource

readonly eventContext?: EventTargetSource

readonly eventName: stringSource

value: undefined | EventHandlerWithOptionsSource

commit(): voidSource

Commits the current part value, causing it to actually be written to the DOM.

Details

handleEvent(event): voidSource

Parameters

event: Event

setValue(value): voidSource

Sets the current part value, but does not write it to the DOM.

Parameters

value: undefined | EventHandlerWithOptions

function isDirectiveSource

Import

import { isDirective } from 'lit-html';

Signature

isDirective(o): o

Parameters

o: unknown

function isIterableSource

Import

import { isIterable } from 'lit-html';

Signature

isIterable(value): value

Parameters

value: unknown

function isPrimitiveSource

Import

import { isPrimitive } from 'lit-html';

Signature

isPrimitive(value): value

Parameters

value: unknown

function isTemplatePartActiveSource

Import

import { isTemplatePartActive } from 'lit-html';

Signature

isTemplatePartActive(part): boolean

Parameters

part: TemplatePart

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

Type

symbol

class NodePartSource

A Part that controls a location within a Node tree. Like a Range, NodePart has start and end locations and can set and update the Nodes between those locations.

Import

import { NodePart } from 'lit-html';

Details

NodeParts support several value types: primitives, Nodes, TemplateResults, as well as arrays and iterables of those types.

Methods and properties

new NodePart(options): NodePartSource

Parameters

options: RenderOptions

endNode: NodeSource

readonly options: RenderOptionsSource

startNode: NodeSource

value: unknownSource

appendInto(container): voidSource

Appends this part into a container.

Parameters

container: Node

Details

This part must be empty, as its contents are not automatically moved.

appendIntoPart(part): voidSource

Appends this part into a parent part.

Parameters

part: NodePart

Details

This part must be empty, as its contents are not automatically moved.

clear(startNode): voidSource

Parameters

startNode: Node

commit(): voidSource

Commits the current part value, causing it to actually be written to the DOM.

Details

insertAfterNode(ref): voidSource

Inserts this part after the ref node (between ref and ref's next sibling). Both ref and its next sibling must be static, unchanging nodes such as those that appear in a literal section of a template.

Parameters

ref: Node

Details

This part must be empty, as its contents are not automatically moved.

insertAfterPart(ref): voidSource

Inserts this part after the ref part.

Parameters

ref: NodePart

Details

This part must be empty, as its contents are not automatically moved.

setValue(value): voidSource

Sets the current part value, but does not write it to the DOM.

Parameters

value: unknown

value partsSource

Import

import { parts } from 'lit-html';

Type

WeakMap<Node, NodePart>

class PropertyCommitterSource

Sets attribute values for PropertyParts, so that the value is only set once even if there are multiple parts for a property.

Import

import { PropertyCommitter } from 'lit-html';

Details

If an expression controls the whole property value, then the value is simply assigned to the property under control. If there are string literals or multiple expressions, then the strings are expressions are interpolated into a string first.

Methods and properties

new PropertyCommitter(element, name, strings): PropertyCommitterSource

Parameters

element: Element
name: string
strings: ReadonlyArray<string>

dirty: booleanSource

readonly element: ElementSource

readonly name: stringSource

readonly parts: ReadonlyArray<AttributePart>Source

readonly single: booleanSource

readonly strings: ReadonlyArray<string>Source

commit(): voidSource

class PropertyPartSource

Import

import { PropertyPart } from 'lit-html';

Methods and properties

new PropertyPart(committer): PropertyPart

Parameters

committer: AttributeCommitter

readonly committer: AttributeCommitterSource

value: unknownSource

commit(): voidSource

Commits the current part value, causing it to actually be written to the DOM.

Details

setValue(value): voidSource

Sets the current part value, but does not write it to the DOM.

Parameters

value: unknown

function removeNodesSource

Removes nodes, starting from start (inclusive) to end (exclusive), from container.

Import

import { removeNodes } from 'lit-html';

Signature

removeNodes(container, start, end): void

Parameters

container: Node
start: null | Node
end: null | Node

function reparentNodesSource

Reparents nodes, starting from start (inclusive) to end (exclusive), into another container (could be the same container), before before. If before is null, it appends the nodes to the container.

Import

import { reparentNodes } from 'lit-html';

Signature

reparentNodes(container, start, end, before): void

Parameters

container: Node
start: null | Node
end: null | Node
before: null | Node

class TemplateSource

An updatable Template that tracks the location of dynamic parts.

Import

import { Template } from 'lit-html';

Methods and properties

new Template(result, element): TemplateSource

Parameters

result: TemplateResult
element: HTMLTemplateElement

readonly element: HTMLTemplateElementSource

readonly parts: Array<TemplatePart>Source

value templateCachesSource

Import

import { templateCaches } from 'lit-html';

Type

Map<string, TemplateCache>

function templateFactorySource

The default TemplateFactory which caches Templates keyed on result.type and result.strings.

Import

import { templateFactory } from 'lit-html';

Signature

templateFactory(result): Template

Parameters

result: TemplateResult

class TemplateInstanceSource

An instance of a Template that can be attached to the DOM and updated with new values.

Import

import { TemplateInstance } from 'lit-html';

Methods and properties

new TemplateInstance(template, processor, options): TemplateInstanceSource

Parameters

template: Template
processor: TemplateProcessor
options: RenderOptions

readonly options: RenderOptionsSource

readonly processor: TemplateProcessorSource

readonly template: TemplateSource

update(values): voidSource

Parameters

values: ReadonlyArray<unknown>

type DirectiveFnSource

Import

import { DirectiveFn } from 'lit-html';

Type

(part: Part) => void

type PartSource

The Part interface represents a dynamic part of a template instance rendered by lit-html.

Import

import { Part } from 'lit-html';

Methods and properties

readonly value: unknownSource

commit(): void

Commits the current part value, causing it to actually be written to the DOM.

Details

setValue(value): void

Sets the current part value, but does not write it to the DOM.

Parameters

value: unknown
The value that will be committed.

type TemplateProcessorSource

Import

import { TemplateProcessor } from 'lit-html';

Methods and properties

handleAttributeExpressions(element, name, strings, options): ReadonlyArray<Part>

Create parts for an attribute-position binding, given the element, attribute name, and string literals.

Parameters

element: Element
The element containing the binding
name: string
The attribute name, including a possible prefix. The name may be prefixed by . (for a property binding), @ (for an event binding) or ? (for a boolean attribute binding).
strings: ReadonlyArray<string>
The array of literal strings that form the static part of the attribute value. There are always at least two strings, even for fully-controlled bindings with a single expression. For example, for the binding attr="${e1}-${e2}", the strings array includes three strings (['', '-', ''])—the text before the first expression (the empty string), the text between the two expressions ('-'), and the text after the last expression (another empty string).
options: RenderOptions

handleTextExpression(options): NodePart

Create parts for a text-position binding.

Parameters

options: RenderOptions

© Google LLC
Licensed under the Creative Commons Attribution 3.0 Unported License.
https://lit.dev/docs/v1/api/lit-html/custom-directives/