Skip to main content

LitElement

Base element class that manages element properties and attributes, and renders a lit-html template.

Import

Details

To define a component, subclass LitElement and implement a render method to provide the component's template. Define properties using the properties property or the property decorator.

attributeChangedCallback(name, _old, value): void

Permalink to attributeChangedCallback View source

Synchronizes property values when attributes change.

Parameters
name
string
_old
null | string
value
null | string

static observedAttributes: Array<string>

Permalink to observedAttributes View source

Returns a list of attributes corresponding to the registered properties.

addController(controller): void

Permalink to addController View source
Parameters
controller
ReactiveController

removeController(controller): void

Permalink to removeController View source
Parameters
controller
ReactiveController

static disableWarning?: (warningKind: WarningKind) => void

Permalink to disableWarning View source

Disable the given warning kind for this class.

Details

This method only exists in development builds, so it should be accessed with a guard like:

Read or set all the enabled warning kinds for this class.

Details

This property is only used in development builds.

static enableWarning?: (warningKind: WarningKind) => void

Permalink to enableWarning View source

Enable the given warning kind for this class.

Details

This method only exists in development builds, so it should be accessed with a guard like:

static addInitializer(initializer): void

Permalink to addInitializer View source
Parameters
initializer
Initializer

static finalize(): boolean

Permalink to finalize View source

Creates property accessors for registered properties, sets up element styling, and ensures any superclasses are also finalized. Returns true if the element was finalized.

static finalized: boolean

Permalink to finalized View source

Ensure this class is marked as finalized as an optimization ensuring it will not needlessly try to finalize.

Details

Note this property name is a string to prevent breaking Closure JS Compiler optimizations. See @lit/reactive-element for more information.

static createProperty(name, options?): void

Permalink to createProperty View source

Creates a property accessor on the element prototype if one does not exist and stores a PropertyDeclaration for the property with the given options. The property setter calls the property's hasChanged property option or uses a strict identity check to determine whether or not to request an update.

Parameters
name
PropertyKey
options?
PropertyDeclaration<unknown, unknown>
Details

This method may be overridden to customize properties; however, when doing so, it's important to call super.createProperty to ensure the property is setup correctly. This method calls getPropertyDescriptor internally to get a descriptor to install. To customize what properties do when they are get or set, override getPropertyDescriptor. To customize the options for a property, implement createProperty like this:

static elementProperties: PropertyDeclarationMap

Permalink to elementProperties View source

Memoized list of all element properties, including any superclass properties. Created lazily on user subclasses when finalizing the class.

static getPropertyDescriptor(name, key, options): {configurable: boolean, enumerable: boolean, get: () => any, set: (value: unknown) => void}

Permalink to getPropertyDescriptor View source

Returns a property descriptor to be defined on the given named property. If no descriptor is returned, the property will not become an accessor. For example,

Parameters
name
PropertyKey
key
string | symbol
options
PropertyDeclaration<unknown, unknown>
Details

static getPropertyOptions(name): PropertyDeclaration<unknown, unknown>

Permalink to getPropertyOptions View source

Returns the property options associated with the given property. These options are defined with a PropertyDeclaration via the properties object or the @property decorator and are registered in createProperty(...).

Parameters
name
PropertyKey
Details

Note, this method should be considered "final" and not overridden. To customize the options for a given property, override createProperty.

User-supplied object that maps property names to PropertyDeclaration objects containing options for configuring reactive properties. When a reactive property is set the element will update and render.

Details

By default properties are public fields, and as such, they 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: true option. Properties marked as state do not reflect from the corresponding attribute

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 set with the state: true option should be used. When needed, state properties can be initialized via public properties to facilitate complex interactions.

Invoked on each update to perform rendering tasks. This method may return any value renderable by lit-html's ChildPart - typically a TemplateResult. Setting properties inside this method will not trigger the element to update.

Node or ShadowRoot into which element DOM should be rendered. Defaults to an open shadowRoot.

Options used when calling attachShadow. Set this property to customize the options for the shadowRoot; for example, to create a closed shadowRoot: {mode: 'closed'}.

Details

Note, these options are used in createRenderRoot. If this method is customized, options should be respected if possible.

Memoized list of all element styles. Created lazily on user subclasses when finalizing the class.

static finalizeStyles(styles?): Array<CSSResultOrNative>

Permalink to finalizeStyles View source

Takes the styles the user supplied via the static styles property and returns the array of styles to apply to the element. Override this method to integrate into a style management system.

Parameters
styles?
CSSResultGroup
Details

Styles are deduplicated preserving the last instance in the list. This is a performance optimization to avoid duplicated styles that can occur especially when composing via subclassing. The last item is kept to try to preserve the cascade order with the assumption that it's most important that last added styles override previous styles.

Array of styles to apply to the element. The styles should be defined using the css tag function or via constructible stylesheets.

enableUpdating(_requestedUpdate): void

Permalink to enableUpdating View source

Note, this method should be considered final and not overridden. It is overridden on the element instance with a function that triggers the first update.

Parameters
_requestedUpdate
boolean

firstUpdated(_changedProperties): void

Permalink to firstUpdated View source

Invoked when the element is first updated. Implement to perform one time work on the element after update.

Parameters
_changedProperties
Map<string | number | symbol, unknown>

Map of changed properties with old values

Details

Setting properties inside this method will trigger the element to update again after this update cycle completes.

getUpdateComplete(): Promise<boolean>

Permalink to getUpdateComplete View source

Override point for the updateComplete promise.

Details

It is not safe to override the updateComplete getter directly due to a limitation in TypeScript which means it is not possible to call a superclass getter (e.g. super.updateComplete.then(...)) when the target language is ES5 (https://github.com/microsoft/TypeScript/issues/338). This method should be overridden instead. For example:

performUpdate(): void | Promise<unknown>

Permalink to performUpdate View source

Performs an element update. Note, if an exception is thrown during the update, firstUpdated and updated will not be called.

Details

Call performUpdate() to immediately process a pending update. This should generally not be needed, but it can be done in rare cases when you need to update synchronously.

Note: To ensure performUpdate() synchronously completes a pending update, it should not be overridden. In LitElement 2.x it was suggested to override performUpdate() to also customizing update scheduling. Instead, you should now override scheduleUpdate(). For backwards compatibility with LitElement 2.x, scheduling updates via performUpdate() continues to work, but will make also calling performUpdate() to synchronously process updates difficult.

requestUpdate(name?, oldValue?, options?): void

Permalink to requestUpdate View source

Requests an update which is processed asynchronously. This should be called when an element should update based on some state not triggered by setting a reactive property. In this case, pass no arguments. It should also be called when manually implementing a property setter. In this case, pass the property name and oldValue to ensure that any configured property options are honored.

Parameters
name?
PropertyKey

name of requesting property

oldValue?
unknown

old value of requesting property

options?
PropertyDeclaration<unknown, unknown>

property options to use instead of the previously configured options

scheduleUpdate(): void | Promise<unknown>

Permalink to scheduleUpdate View source

Schedules an element update. You can override this method to change the timing of updates by returning a Promise. The update will await the returned Promise, and you should resolve the Promise to allow the update to proceed. If this method is overridden, super.scheduleUpdate() must be called.

Details

For instance, to schedule updates to occur just before the next frame:

shouldUpdate(_changedProperties): boolean

Permalink to shouldUpdate View source

Controls whether or not update should be called when the element requests an update. By default, this method always returns true, but this can be customized to control when to update.

Parameters
_changedProperties
Map<string | number | symbol, unknown>

Map of changed properties with old values

update(changedProperties): void

Permalink to update View source

Updates the element. This method reflects property values to attributes and calls render to render DOM via lit-html. Setting properties inside this method will not trigger another update.

Parameters
changedProperties
Map<string | number | symbol, unknown>

Map of changed properties with old values

updateComplete: Promise<boolean>

Permalink to updateComplete View source

Returns a Promise that resolves when the element has completed updating. The Promise value is a boolean that is true if the element completed the update without triggering another update. The Promise result is false if a property was set inside updated(). If the Promise is rejected, an exception was thrown during the update.

Details

To await additional asynchronous work, override the getUpdateComplete method. For example, it is sometimes useful to await a rendered element before fulfilling this Promise. To do this, first await super.getUpdateComplete(), then any subsequent state.

updated(_changedProperties): void

Permalink to updated View source

Invoked whenever the element is updated. Implement to perform post-updating tasks via DOM APIs, for example, focusing an element.

Parameters
_changedProperties
Map<string | number | symbol, unknown>

Map of changed properties with old values

Details

Setting properties inside this method will trigger the element to update again after this update cycle completes.

willUpdate(_changedProperties): void

Permalink to willUpdate View source
Parameters
_changedProperties
Map<string | number | symbol, unknown>

Object specifying options for controlling lit-html rendering. Note that while render may be called multiple times on the same container (and renderBefore reference node) to efficiently update the rendered content, only the options passed in during the first render are respected during the lifetime of renders to that unique container + renderBefore combination.

Import

Methods and properties

creationScope?: {importNode: (node: Node, deep?: boolean) => Node}

Permalink to creationScope View source

Node used for cloning the template (importNode will be called on this node). This controls the ownerDocument of the rendered DOM, along with any inherited context. Defaults to the global document.

An object to use as the this value for event listeners. It's often useful to set this to the host component rendering a template.

The initial connected state for the top-level part being rendered. If no isConnected option is set, AsyncDirectives will be connected by default. Set to false if the initial render occurs in a disconnected tree and AsyncDirectives should see isConnected === false for their initial render. The part.setConnected() method must be used subsequent to initial render to change the connected state of the part.

renderBefore?: null | ChildNode

Permalink to renderBefore View source

A DOM node before which to render content in the container.