Skip to main content

Decorators

Class decorator factory that defines the decorated class as a custom element.

Import

Signature

customElement(tagName): (classOrDescriptor: Constructor<MDN HTMLElement> | ClassDescriptor) => any

Parameters

tagName
string

The name of the custom element to define.

Details

Adds event listener options to a method used as an event listener in a lit-html template.

Import

Signature

eventOptions(options): (protoOrDescriptor: ReactiveElement | ClassElement, name?: string) => any

Parameters

options
AddEventListenerOptions

An object that specifies event listener options as accepted by EventTarget#addEventListener and EventTarget#removeEventListener.

Current browsers support the capture, passive, and once options. See: https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#Parameters

A property decorator which creates a reactive property that reflects a corresponding attribute value. When a decorated property is set the element will update and render. A PropertyDeclaration may optionally be supplied to configure property features.

Import

Signature

property(options?): (protoOrDescriptor: Object | ClassElement, name?: string | number | symbol) => any

Parameters

options?
PropertyDeclaration

Details

This decorator should only be used for public fields. As public fields, properties should be considered as primarily settable by element users, either via attribute or the property itself.

Generally, properties that are changed by the element should be private or protected fields and should use the state decorator.

However, sometimes element code does need to set a public property. This should typically only be done in response to user interaction, and an event should be fired informing the user; for example, a checkbox sets its checked property when clicked and fires a changed event. Mutating public properties should typically not be done for non-primitive (object or array) properties. In other cases when an element needs to manage state, a private property decorated via the state decorator should be used. When needed, state properties can be initialized via public properties to facilitate complex interactions.

A property decorator that converts a class property into a getter that executes a querySelector on the element's renderRoot.

Import

Signature

query(selector, cache?): (protoOrDescriptor: ReactiveElement | ClassElement, name?: string) => any

Parameters

selector
string

A DOMString containing one or more selectors to match.

cache?
boolean

An optional boolean which when true performs the DOM query only once and caches the result.

See: https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector

A property decorator that converts a class property into a getter that executes a querySelectorAll on the element's renderRoot.

Import

Signature

queryAll(selector): (protoOrDescriptor: ReactiveElement | ClassElement, name?: string) => any

Parameters

selector
string

A DOMString containing one or more selectors to match.

See: https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelectorAll

A property decorator that converts a class property into a getter that returns the assignedNodes of the given named slot. Note, the type of this property should be annotated as NodeListOf<HTMLElement>.

Import

Signature

queryAssignedNodes(slotName?, flatten?, selector?): (protoOrDescriptor: ReactiveElement | ClassElement, name?: string) => any

Parameters

slotName?
string

A string name of the slot.

flatten?
boolean

A boolean which when true flattens the assigned nodes, meaning any assigned nodes that are slot elements are replaced with their assigned nodes.

selector?
string

A string which filters the results to elements that match the given css selector.

  • @example

A property decorator that converts a class property into a getter that returns a promise that resolves to the result of a querySelector on the element's renderRoot done after the element's updateComplete promise resolves. When the queried property may change with element state, this decorator can be used instead of requiring users to await the updateComplete before accessing the property.

Import

Signature

queryAsync(selector): (protoOrDescriptor: ReactiveElement | ClassElement, name?: string) => any

Parameters

selector
string

A DOMString containing one or more selectors to match.

See: https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector

Declares a private or protected reactive property that still triggers updates to the element when it changes. It does not reflect from the corresponding attribute.

Import

Signature

state(options?): (protoOrDescriptor: Object | ClassElement, name?: string | number | symbol) => any

Parameters

options?
InternalPropertyDeclaration

Details

Properties declared this way must not be used from HTML or HTML templating systems, they're solely for properties internal to the element. These properties may be renamed by optimization tools like closure compiler.

Import

Methods and properties

hasChanged(value, oldValue): boolean

Permalink to hasChanged

A function that indicates if a property should be considered changed when it is set. The function should take the newValue and oldValue and return true if an update should be requested.

Parameters
value
Type
oldValue
Type