LitElement-based components update asynchronously in response to observed property changes. Property changes are batched—if more properties change after an update is requested, but before the update starts, all of the changes are captured in the same update.
At a high level, the update lifecycle is:
A property is set.
Check whether an update is needed. If an update is needed, request one.
Perform the update:
Process properties and attributes.
Render the element.
Resolve a Promise, indicating that the update is complete.
The browser executes JavaScript code by processing a queue of tasks in the event loop. In each iteration of the event loop, the browser takes a task from the queue and runs it to completion.
When the task completes, before taking the next task from the queue, the browser allocates time to perform work from other sources—including DOM updates, user interactions, and the microtask queue.
By default, LitElement updates are requested asynchronously, and queued as microtasks. This means that Step 3 above (Perform the update) is executed at the end of the next iteration of the event loop.
You can change this behavior so that Step 3 awaits a Promise before performing the update. See performUpdate for more information.
Common reasons to hook into the custom element lifecycle or the LitElement update lifecycle are initializations, managing derived data, and dealing with events that originate outside of your element's template. The following list provides some common use cases and approaches. In several cases there is more than one way to achieve a certain goal. Reading this list along with the detailed technical reference will provide you with a rather complete picture and enable you to decide what fits your component's needs best.
Use property.hasChanged for checking "Is this a change? Do I want to run the update lifecycle?".
Use firstUpdated for initializing private fields from DOM attributes (as the constructor doesn't have access to them). Note that render has already run at this point and your changes might trigger another update lifecycle. If it's imperative that you get access to attribute values before the first render happens, consider using connectedCallback, but you'll need to do the extra logic for figuring out the "first" update yourself as connectedCallback can be called multiple times.
Use updated for keeping derived data up to date or reacting to changes. If you find, that you're causing re-renders, consider using update instead.
Use custom JS property getters for derived data that is "cheap" to calculate and if its not likely to change often and your element doesn't re-render often.
Use requestUpdate to trigger an update lifecycle when LitElement cannot pick it up. (E.g. if you have an observed property that is an array, and you add an item to that array instead of replacing the entire array, LitElement won't "see" this change, because the reference to the array didn't change.)
Property changes inside this method will not trigger an element update.
When an update is performed, the performUpdate() method is called. This method calls a number of other lifecycle methods.
Any changes that would normally trigger an update which occur while a component is updating do not schedule a new update. This is done so that property values can be computed during the update process. Properties changed during the update are reflected in the changedProperties map, so subsequent lifecycle methods can act on the changes.
By default, performUpdate is scheduled as a microtask after the end of the next execution of the browser event loop. To schedule performUpdate, implement it as an asynchronous method that awaits some state before calling super.performUpdate(). For example:
Map. Keys are the names of changed properties; Values are the corresponding previous values.
Returns
Boolean
If true, update proceeds. Default return value is true.
Updates?
No
Property changes inside this method will not trigger an element update.
Controls whether an update should proceed. Implement shouldUpdate to specify which property changes should cause updates. By default, this method always returns true.
Example: Customize which property changes should cause updates
Map. Keys are the names of changed properties; Values are the corresponding previous values.
Updates?
No
Property changes inside this method do not trigger an element update.
Reflects property values to attributes and calls render to render DOM via lit-html. Provided here for reference. You don't need to override or call this method. But if you override it, make sure to call super.update(changedProperties) or render will never be called.
To await additional state before fulfilling the updateComplete promise, override the _getUpdateComplete method. For example, it may be useful to await the update of a child element here. First await super._getUpdateComplete(), then any subsequent state.
It's recommended to override the _getUpdateComplete method instead of the updateComplete getter to ensure compatibility with users who are using TypeScript's ES5 output (see TypeScript#338).
Mutations (changes to object subproperties and array items) are not observable. Instead, either rewrite the whole object, or call requestUpdate after a mutation.
// Option 1: Rewrite whole object, triggering an update