If a field’s value changes, and the field is used in a template or in a getter of a property that’s used in a template, the component rerenders and displays the new value. If a field is assigned an object or an array, the framework observes some changes to the internals of the object or array, such as when you assign a new value.
When a component rerenders, the expressions used in the template are reevaluated and the renderedCallback() lifecycle hook executes.
Primitive fields—like booleans, numbers, and strings—are reactive. LWC tracks field value changes in a shallow fashion. Changes are detected when a new value is assigned to the field by comparing the value identity using ===.
When manipulating complex types like objects and arrays, you must create a new object and assign it to the field for the change to be detected.
1import { LightningElement } from "lwc";
2
3export default class ReactivityExample extends LightningElement {
4 bool = true;
5 number = 42;
6 obj = { name: "John" };
7
8 checkMutation() {
9 this.bool = false; // Mutation detected
10
11 this.number = 42; // No mutation detected: previous value is equal to the newly assigned value
12 this.number = 43; // Mutation detected
13
14 this.obj.name = "Bob"; // No mutation detect: `obj` field value is not reassigned
15 this.obj = { name: "John" }; // Mutation detected - redefining the object with the same value creates a new object
16 this.obj = { ...this.obj, title: "CEO" }; // Mutation detected
17 }
18}To deeply track mutations made to the field value for a complex object, use the @track decorator.
To observe changes to the properties of an object or to the elements of an array, decorate the field with @track.
When a field is decorated with @track, Lightning Web Components tracks changes to the internal values of:
{}[]The framework observes mutations made to plain objects and arrays in a recursive fashion, including nested objects, nested arrays, and a mix of objects and arrays. Cyclic references are also handled.
However, the framework doesn’t observe mutations made to complex objects, such as objects inheriting from Object, class instances, Date, Set, or Map.
To tell the framework to observe changes to the properties of an object, decorate the field with @track.
As discussed earlier, without using @track, the framework observes changes that assign a new value to the field. If the new value is not === to the previous value, the component rerenders.
Note
For example, let’s change the code a bit to declare the fullName field, which contains an object with two properties, firstName and lastName. The framework observes changes that assign a new value to fullName.
1fullName = { firstName: "", lastName: "" };This code assigns a new value to the fullName field, so the component rerenders.
1// Component rerenders.
2this.fullName = { firstName: "John", lastName: "Doe" };However, if we assign a new value to one of the object’s properties, the component doesn’t rerender, because the properties aren’t observed.
1// Component doesn't rerender.
2this.fullName.firstName = "John";The framework observes changes that assign a new value to the fullName field. This code doesn’t do that, instead it assigns a new value to the firstName property of the fullName object.
To tell the framework to observe changes to the object’s properties, decorate the fullName field with @track. Now if we change either property, the component rerenders.
1// Component rerenders.
2@track fullName = { firstName : '', lastName : ''};
3this.fullName.firstName = 'John';If a property contains an object, to track changes on the object’s properties, annotate the property with @track. To understand, let’s modify our example. Our example initializes firstName and lastName to empty strings, which are primitive values, so the component rerenders when they change.
A component rerenders only if a property accessed during the previous rendering cycle is updated, even when the object is annotated with @track. This prevents the component from rerendering excessively,
Consider this tracked object and a getter that prints the object’s properties.
1@track obj = {value1: 'Hello'};
2
3get words() {
4 return Object.entries(this.obj)
5 .map(([key, value]) => ({key, value}));
6 }During the first render cycle, the framework records that obj.value1 is accessed. Any mutation to obj that doesn’t affect value1 is ignored since it doesn’t impact the rendered content. Therefore, a change to value1 triggers a rerendering, but adding a new property to obj or a change to value2 doesn’t trigger a rerendering.
1// Component rerenders.
2setValue1(e) {
3 this.obj.value1 = 'Hello World';
4}
5
6// Component doesn’t rerender.
7setValue2(e) {
8 this.obj.value2 = 'Hello LWC';
9}To rerender your component when adding a new property, assign the object to a new object with both values.
1setValue2(e) {
2 this.obj = {
3 ...this.obj,
4 value2: 'Hello LWC'
5 };
6}Another use case for @track is to tell the framework to observe changes to the elements of an array.
If you don’t use @track, the framework observes changes that assign a new value to the field.
1arr = ["a", "b"];The component rerenders when you assign a new value to arr.
1// Component rerenders.
2this.arr = ["x", "y", "z"];However, if we update or add an element in the array, the component doesn’t rerender.
1// Component doesn’t rerender.
2this.arr[0] = "x";
3this.arr.push("c");To tell the framework to observe changes to the array’s elements, decorate the arr field with @track Additionally, the framework doesn’t automatically convert the array to a string for updates to the array’s elements. To return the updated string, use a getter to convert the elements of the array to a string using join().
1@track arr = ['a','b'];
2
3get computedArray() { return this.arr.join(','); }
4
5update() {
6 this.arr[0] = 'x';
7 this.arr.push('c');
8}Let’s look at a component with a field, x, of type Date. The template has a few buttons that change the internal state of x. This example highlights that new Date() creates an object, as it is not a plain JavaScript object internal state mutation will not be observed by the LWC engine, even though the code uses @track.
1// trackDate.js
2import { LightningElement, track } from "lwc";
3export default class TrackDate extends LightningElement {
4 @track x = new Date();
5
6 initDate() {
7 this.x = new Date();
8 }
9
10 updateDate() {
11 this.x.setHours(7); // No mutation detected
12 }
13}Similarly to our previous example, the template has a few buttons that change the internal state of x.
1<!-- trackDate.html -->
2<template>
3 <p>Date: {x}</p>
4
5 <button onclick={initDate}>Init</button>
6 <button onclick={updateDate}>Update</button>
7</template>When you click the Init button, the change is observed and the template is rerendered. Lightning Web Components observes that x is pointing to a new Date object. However, when you click Update, the template isn’t rerendered. Lightning Web Components doesn’t observe changes to the value of the Date object.
To ensure that the template is rerendered when the value changes, clone the existing date and update its value.
1updateDate() {
2 const cloned = new Date(this.x.getTime());
3 cloned.setHours(7);
4
5 // Assign the new date instance to rerender the component.
6 this.x = cloned;
7}When you set a property to a value that can’t be tracked, a warning is logged. If you’re trying to debug a scenario where the component isn’t rerendering on change, look in your browser console. For our example, the browser console logs this helpful warning:
Property "x" of [object:vm TrackDate] is set to a non-trackable object, which means changes into that object cannot be observed.
Note
When you enter a value in the First Name or Last Name field, the component converts it to uppercase and displays it.
1<!-- helloExpressions.html -->
2
3<template>
4 <lightning-card title="HelloExpressions" icon-name="custom:custom14">
5 <div class="slds-m-around_medium">
6 <lightning-input
7 name="firstName"
8 label="First Name"
9 onchange={handleChange}
10 ></lightning-input>
11 <lightning-input
12 name="lastName"
13 label="Last Name"
14 onchange={handleChange}
15 ></lightning-input>
16 <p class="slds-m-top_medium">Uppercased Full Name: {uppercasedFullName}</p>
17 </div>
18 </lightning-card>
19</template>The component’s class defines the firstName and lastName fields. Because they’re used in the getter of a property that’s used in the template (uppercasedFullName), the component rerenders when their values change.
1// helloExpressions.js
2
3import { LightningElement } from "lwc";
4
5export default class TrackExample extends LightningElement {
6 firstName = "";
7 lastName = "";
8
9 handleChange(event) {
10 const field = event.target.name;
11 if (field === "firstName") {
12 this.firstName = event.target.value;
13 } else if (field === "lastName") {
14 this.lastName = event.target.value;
15 }
16 }
17
18 get uppercasedFullName() {
19 return `${this.firstName} ${this.lastName}`.trim().toUpperCase();
20 }
21}Fields are reactive. Expando properties, which are properties added to an object at runtime, aren’t reactive.
Note
See the helloExpressions component in the lwc-recipes repository.
Tip
See Also
Release Preview
j