Options
All
  • Public
  • Public/Protected
  • All
Menu

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.

noinheritdoc

Hierarchy

  • any
    • UpdatingElement

Index

Constructors

constructor

Properties

Static Protected [finalized]

[finalized]: boolean = true

Marks class as having finished creating properties.

Static properties

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

Accessors

Protected hasUpdated

  • get hasUpdated(): number

updateComplete

  • get updateComplete(): Promise<unknown>
  • 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.

    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.

    Returns Promise<unknown>

    The Promise returns a boolean that indicates if the update resolved without triggering another update.

Static observedAttributes

  • get observedAttributes(): string[]

Methods

Protected _getUpdateComplete

  • _getUpdateComplete(): Promise<unknown>
  • Override point for the updateComplete promise.

    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; } }

    Returns Promise<unknown>

attributeChangedCallback

  • attributeChangedCallback(name: string, old: string | null, value: string | null): void
  • Synchronizes property values when attributes change.

    Parameters

    • name: string
    • old: string | null
    • value: string | null

    Returns void

connectedCallback

  • connectedCallback(): void

disconnectedCallback

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

    Returns void

Protected enableUpdating

  • enableUpdating(): void

Protected firstUpdated

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

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

    Parameters

    • _changedProperties: PropertyValues

      Map of changed properties with old values

    Returns void

Protected initialize

  • initialize(): void
  • Performs element initialization. By default captures any pre-set values for registered properties.

    Returns void

Protected performUpdate

  • performUpdate(): void | Promise<unknown>
  • Performs an element update. Note, if an exception is thrown during the update, firstUpdated and updated will not be called.

    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:

    protected async performUpdate(): Promise<unknown> {
      await new Promise((resolve) => requestAnimationFrame(() => resolve()));
      super.performUpdate();
    }

    Returns void | Promise<unknown>

requestUpdate

  • requestUpdate(name?: PropertyKey, oldValue?: unknown): Promise<unknown>
  • 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

    • Optional name: PropertyKey

      (optional) name of requesting property

    • Optional oldValue: unknown

      (optional) old value of requesting property

    Returns Promise<unknown>

    A Promise that is resolved when the update completes.

Protected requestUpdateInternal

  • requestUpdateInternal(name?: PropertyKey, oldValue?: unknown, options?: PropertyDeclaration): void
  • 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

    Returns void

Protected shouldUpdate

  • 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: PropertyValues

      Map of changed properties with old values

    Returns boolean

Protected update

  • 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: PropertyValues

      Map of changed properties with old values

    Returns void

Protected updated

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

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

    Parameters

    • _changedProperties: PropertyValues

      Map of changed properties with old values

    Returns void

Static createProperty

  • 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.

    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); }

    nocollapse

    Parameters

    Returns void

Static Protected finalize

  • finalize(): void
  • Creates property accessors for registered properties and ensures any superclasses are also finalized.

    nocollapse

    Returns void

Static Protected getPropertyDescriptor

  • getPropertyDescriptor(name: PropertyKey, key: string | symbol, options: PropertyDeclaration): { configurable: boolean; enumerable: boolean; get: any; set: any }
  • 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,

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

    nocollapse

    Parameters

    Returns { configurable: boolean; enumerable: boolean; get: any; set: any }

Static Protected getPropertyOptions

  • 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(...).

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

    nocollapse
    final

    Parameters

    • name: PropertyKey

    Returns PropertyDeclaration<unknown, unknown>

Generated using TypeDoc