You're viewing docs for an older version of Lit. Click here for the latest version.

UpdatingElement

Import

Type

ComplexAttributeConverter

Change function that returns true if value is different from oldValue. This method is used as the default for a property's hasChanged function.

Import

Signature

notEqual(value, old): boolean

Parameters

value
unknown
old
unknown

Base element class which manages element properties and attributes. When properties change, the update method is asynchronously called. This method should be supplied by subclassers to render updates as desired.

Import

Methods and properties

static finalized: boolean

Permalink to finalized View source

Marks class as having finished creating properties.

User-supplied object that maps property names to PropertyDeclaration objects containing options for configuring the property.

updateComplete: Promise<unknown>

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.

static observedAttributes: Array<string>

Permalink to observedAttributes View source

Returns a list of attributes corresponding to the registered properties.

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

Allows for super.disconnectedCallback() in extensions while reserving the possibility of making non-breaking feature additions when disconnecting at some point in the future.

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<unknown>

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:

class MyElement extends LitElement { async getUpdateComplete() { await super.getUpdateComplete(); await this._myChild.updateComplete; } }

Performs element initialization. By default captures any pre-set values for registered properties.

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

You can override this method to change the timing of updates. If this method is overridden, super.performUpdate() must be called.

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

requestUpdate(name?, oldValue?): Promise<unknown>

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 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. Returns the updateComplete Promise which is resolved when the update completes.

Parameters
name?
PropertyKey

(optional) name of requesting property

oldValue?
unknown

(optional) old value of requesting property

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

Permalink to requestUpdateInternal View source

This protected version of requestUpdate does not access or return the updateComplete promise. This promise can be overridden and is therefore not free to access.

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

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. It can be overridden to render and keep updated element DOM. Setting properties inside this method will not trigger another update.

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

Map of changed properties with old values

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.

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 createProperty(name, options) { options = Object.assign(options, {myOption: true}); super.createProperty(name, options); }

Creates property accessors for registered properties and ensures any superclasses are also finalized.

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

class MyElement extends LitElement { static getPropertyDescriptor(name, key, options) { const defaultDescriptor = super.getPropertyDescriptor(name, key, options); const setter = defaultDescriptor.set; return { get: defaultDescriptor.get, set(value) { setter.call(this, value); // custom action. }, configurable: true, enumerable: true } } }

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.

Converts property values to and from attribute values.

Import

Methods and properties

fromAttribute(value, type?): Type

Permalink to fromAttribute

Function called to convert an attribute value to a property value.

Parameters
value
null | string
type?
TypeHint

toAttribute(value, type?): unknown

Permalink to toAttribute

Function called to convert a property value to an attribute value.

Parameters
value
Type
type?
TypeHint
Details

It returns unknown instead of string, to be compatible with https://github.com/WICG/trusted-types (and similar efforts).

Import

Signature

HasChanged(value, old): boolean

Parameters

value
unknown
old
unknown

Defines options for a property accessor.

Import

Methods and properties

readonly attribute?: string | boolean

Permalink to attribute View source

Indicates how and whether the property becomes an observed attribute. If the value is false, the property is not added to observedAttributes. If true or absent, the lowercased property name is observed (e.g. fooBar becomes foobar). If a string, the string value is observed (e.g attribute: 'foo-bar').

readonly converter?: AttributeConverter<Type, TypeHint>

Permalink to converter View source

Indicates how to convert the attribute to/from a property. If this value is a function, it is used to convert the attribute value a the property value. If it's an object, it can have keys for fromAttribute and toAttribute. If no toAttribute function is provided and reflect is set to true, the property value is set directly to the attribute. A default converter is used if none is provided; it supports Boolean, String, Number, Object, and Array. Note, when a property changes and the converter is used to update the attribute, the property is never updated again as a result of the attribute changing, and vice versa.

readonly noAccessor?: boolean

Permalink to noAccessor View source

Indicates whether an accessor will be created for this property. By default, an accessor will be generated for this property that requests an update when set. If this flag is true, no accessor will be created, and it will be the user's responsibility to call this.requestUpdate(propertyName, oldValue) to request an update when the property changes.

readonly reflect?: boolean

Permalink to reflect View source

Indicates if the property should reflect to an attribute. If true, when the property is set, the attribute is set using the attribute name determined according to the rules for the attribute property option and the value of the property converted using the rules from the converter property option.

readonly type?: TypeHint

Permalink to type View source

Indicates the type of the property. This is used only as a hint for the converter to determine how to convert the attribute to/from a property.

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

Map of properties to PropertyDeclaration options. For each property an accessor is made, and the property is processed according to the PropertyDeclaration options.

Import

Map of changed properties with old values. Takes an optional generic interface corresponding to the declared element properties.

Import

Type

keyof T ? Map<keyof T, unknown> : never