Decorators

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

Import

import { customElement } from 'lit/decorators.js';

Signature

customElement(tagName): (classOrDescriptor: ClassDescriptor | CustomElementClass) => any

Parameters

tagName

string

The tag name of the custom element to define.

Details

@customElement('my-element')
class MyElement extends LitElement {
  render() {
    return html``;
  }
}

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

Import

import { eventOptions } from 'lit/decorators.js';

Signature

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

Parameters

options

AddEventListenerOptions

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

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

import { property } from 'lit/decorators.js';

Signature

property(options?): (protoOrDescriptor: Object | ClassElement, name?: PropertyKey) => any

Parameters

options?

PropertyDeclaration<unknown, unknown>

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.

class MyElement {
  @property({ type: Boolean })
  clicked = false;
}

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

Import

import { query } from 'lit/decorators.js';

Signature

query(selector, cache?): (protoOrDescriptor: ReactiveElement | ClassElement, name?: PropertyKey) => 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.

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

Import

import { queryAll } from 'lit/decorators.js';

Signature

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

Parameters

selector

string

A DOMString containing one or more selectors to match.

A property decorator that converts a class property into a getter that returns the assignedElements of the given slot. Provides a declarative way to use HTMLSlotElement.assignedElements.

Import

import { queryAssignedElements } from 'lit/decorators.js';

Signature

queryAssignedElements(options?): (protoOrDescriptor: ReactiveElement | ClassElement, name?: PropertyKey) => any

Parameters

options?

QueryAssignedElementsOptions

Details

Can be passed an optional QueryAssignedElementsOptions object. Example usage:

class MyElement {
  @queryAssignedElements({ slot: 'list' })
  listItems!: Array<HTMLElement>;
  @queryAssignedElements()
  unnamedSlotEls!: Array<HTMLElement>;
  render() {
    return html`
      <slot name="list"></slot>
      <slot></slot>
    `;
  }
}

Note, the type of this property should be annotated as Array<HTMLElement>.

A property decorator that converts a class property into a getter that returns the assignedNodes of the given slot.

Import

import { queryAssignedNodes } from 'lit/decorators.js';

Signature

queryAssignedNodes(options?): TSDecoratorReturnType

Parameters

options?

QueryAssignedNodesOptions

Details

Can be passed an optional QueryAssignedNodesOptions object. Example usage:

class MyElement {
  @queryAssignedNodes({slot: 'list', flatten: true})
  listItems!: Array<Node>;
  render() {
    return html`
      <slot name="list"></slot>
    `;
  }
}

Note the type of this property should be annotated as Array<Node>. Use the queryAssignedElements decorator to list only elements, and optionally filter the element list using a CSS selector.

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

import { queryAsync } from 'lit/decorators.js';

Signature

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

Parameters

selector

string

A DOMString containing one or more selectors to match.

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

import { state } from 'lit/decorators.js';

Signature

state(options?): (protoOrDescriptor: Object | ClassElement, name?: PropertyKey) => any

Parameters

options?

InternalPropertyDeclaration<unknown>

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

import { InternalPropertyDeclaration } from 'lit/decorators.js';

Options for the queryAssignedElements decorator. Extends the options that can be passed into HTMLSlotElement.assignedElements.

Import

import { QueryAssignedElementsOptions } from 'lit/decorators.js';

Options for the queryAssignedNodes decorator. Extends the options that can be passed into HTMLSlotElement.assignedNodes.

Import

import { QueryAssignedNodesOptions } from 'lit/decorators.js';