📣 UPDATE! 📣
Now lit-html and LitElement are unified under Lit.
I'm writing new posts about Lit, meanwhile you can:
- read this post because the principles are the same
- upgrade your code with this guide
- visit Lit site to know what's new
You can also use lit-html standalone
Although lit-html is very efficient rendering, it is better to render only when necessary. That is why LitElement differs the re-rendering of the UI by batching the property updates. In other words, re-rendering is done asynchronously to ensure efficiency and good performance. Let's see how the update process works.
Recall from the previous post that all the properties defined in the properties
getter become properties "controlled" by LitElement.
For each property defined in the properties
getter, LitElement will generate:
- a
hasChanged
function - a setter and a getter
- an observed attribute
- a
fromAttribute
function - a
toAttribute
function
In particular, we are interested in the hasChanged
function and the setters because they play an important role in the update life cycle.
Almost all the "magic" is based on the setter that causes the component to be re-rendered when the property changes. First, it checks if the property has changed (invoking the hasChanged
function) and, if that is the case, it will make a rendering request.
Also, if the property is reflected in an attribute, the setter will update the observed attribute using the toAttribute
function.
In the LitElement class we find the following methods that participate in the update of the UI:
- requestUpdate
- performUpdate
- shouldUpdate
- update
- render
- firstUpdated
- updated
- updateComplete
Now that we have seen the main pieces involved in the re-rendering, we will go into detail on how this process occurs.
The update cycle in action
Imagine you have a function with this piece of code:
const el = document.querySelector('#myElement');
el.title = 'Movements'; //previous value was 'No title'
el.icon = 'book.ico'; //previous value was undefined
await el.updateComplete;
- 1. The
title
property setter is executed. This setter callshasChanged
function of thetitle
property. As it has changed, it returnstrue
and in that case it callsperformUpdate
, a method of the LitElement class. This method verifies if there is a previous request pending, in that case it does nothing. If there isn't, it will create a micro-task (a promise) to execute the rendering. This is LitElement's way of asynchronously executing therender
method and batch property changes. - 2. We continue with the following line. Now the
icon
property setter is executed. The setter callshasChanged
function, which returnstrue
, so it calls theperformUpdate
method, but as a UI update operation is already pending, it does nothing else. - 3. Finally, our code is awaiting for the
updateComplete
promise to be resolved, that will occur when the update cycle is over. - 4. Now that there are no tasks on the stack, it is time to execute the micro task that was scheduled (in the step 1). It does the following:
- 4.1. It invokes
shouldUpdate
, another method of the LitElement class. This method receives the properties that have changed and their old values. The purpose of this method is to evaluate all the batched changes that have occurred and based on that decide whether or not the update should be done. By default it returnstrue
, but LitElement gives us this hook in case we want to put a special logic to avoid the update. Following our example,shouldUpdate
receivestitle => 'No title'
,icon => undefined
and returnstrue
, so the update continues. - 4.2. It executes the
update
method of the LitElement class. Here the changes are reflected to the attributes to maintain synchrony between properties and attributes (only for those properties defined withreflect
). Then it calls therender
method. - 4.2.1. The
render
function is executed, the DOM is updated. - 4.2.2. If it is the first time the component is rendered, the
firstUpdated
method will be executed. It's a hook that LitElement gives us to over-write if we need to do initialization tasks once the component is rendered. - 4.2.3. Then the
updated
method of the LitElement class is executed. This is another hook. UnlikefirstUpdated
, this method will always be called after every rendering. - 4.2.4. The
updateComplete
promise get resolved.
👉 All the properties defined in the
properties
getter become properties "controlled" by LitElement and any update of their values will cause a rendering. This is why we should put there only the properties that affect the visual representation of the component: those that we have used in the template.
For example, if we have adebug
property that is used to indicate if traces are written byconsole.log
, changing this property should not cause an UI update.
Live example
To understand it better, I have made this very silly component. The important part is that I have traced each method of the update lifecycle.
When the component is rendered the first time you can find among the traces that there is an invocation to the
firstUpdated
method.I have traced the
_requestUpdate
and_enqueueUpdate
methods that are private methods ofUpdatingElement
which is the class of whichLitElement
class extends. Although these methods are not an "official" part of the update lifecycle, seeing how LitElement uses them internally helps to understand the update process. We can see that_requestUpdate
is called for every property that changes but_enqueueUpdate
it's called only once: with the first property that changed. When there's an update process pending,_enqueueUpdate
is not invoked again.The first time you press the button, it will update the
title
andicon
properties. At this moment the component will be already rendered so you won't find a call tofirstUpdate
.The second time you press the button, it will update again the
title
andicon
properties with the same values it did before. As the property values have no changes, the update cycle is not triggered.I have included the source code of the
UpdatingElement
class because I think you can understand it and see in detail how the UI update process is implemented.
requestUpdate
Sometimes it may be necessary to manually trigger the re-rendering cycle. It is not enough to invoke the render
method, because as we have seen, the process is much more complex. For these cases, LitElement provides the requestUpdate
method that will trigger the whole lifecycle update.
A typical case where we should invoke requestUpdate
is when we define our own setter and we want that a change in the property to cause a re-rendering. As we have seen before, for each controlled property LitElement generates a setter that evaluates whether the property has changed and if so, it updates the UI. But when we write our own setter, we lose the setter that would be generated by LitElement, because of this, we have to do by ourselves what LitElement does. We should do:
set title(value) {
if (this._title !=== value) {
const oldValue = this._title;
this._title = value;
this.requestUpdate('title', oldValue); // Called from within a custom property setter
}
}
👉 When we invoke
requestUpdate
from a setter we must pass the property name and the old value as arguments. On the other hand, if we force a re-render from elsewhere,requestUpdate
has no arguments.
This is the end
With this last topic about the UI update lifecycle we complete the basics of LitElement. You already have the fundamental knowledge to continue your path in lit-html and LitElement.
To go deeper in these libraries I highly recommend reading the official documentation. It's It is very clear, concise and very well organised. In addition, each topic is accompanied by a live example in Stackblitz.
I also suggest you read the source code of lit-html and LitElement. It is relatively short, well documented and with what you already know you will not find it difficult to understand. This way everything will be much clearer.
Last but not least, two important contributions from the community:
- awesome lit - A wonderful collection of resources made by @serhiikulykov.
- open-wc - Web component recommendations with a bunch of powerful and battle-tested setup for sharing open source web components.
Last words...
With this post I finish my series on LitElement. I hope you found it useful and enjoyed it as much as I did writing it. Thank you for having come this far! ❤️
Top comments (1)
Well DONE !