Lightning Web Components - the art of Tracking

On Friday I wrote an excited blog post on the introduction of Lightning Web Components.

One of the things I mentioned was that I didn't quite get how '@track' was supposed to work

Since then, I've found the documentation (add /docs/component-library/documentation/lwc/lwc.get_started_introduction to the end of your Salesforce URL), read it, got confused by my memory, wrote a test-rig and looked at it all in depth.

On the surface, it's simple, but there are some complications, which were the cause of my confusion...

In the documentation it says the following:

Both @track and @api mark a property as reactive. If the property’s value changes, the component re-renders.

OK, nice and simple. So what does that mean?

A single untracked property

Testing with a simple component that contains a single property that is not tracked I found the following behaviour:

Javascript component

    export default class TrackExperiments extends LightningElement {
        primitiveUntracked;

        handlePrimitiveUntrackChanged( event ) {
            this.primitiveUntracked = event.target.value;
        }
    }

Template

    <p>The value is: {primitiveUntracked}</p>
    <lightning-input label="Input without an on-change handler"
                        type="Text"
                        value={primitiveUntracked}></lightning-input>
    <lightning-input label="Input with an on-change handler"
                        type="Text"
                        value={primitiveUntracked}
                        onchange={handlePrimitiveUntrackChanged}></lightning-input>

• Changing the value defined in either of the inputs will not result in the rendered value changing.
• Changing the value defined in the input without the onchange handler will not change the Javascript property.
• Changing the value defined in the input that does have an onchange handler will update the Javascript property.

So, fairly straightforward, and maybe in-line with what you would expect:

• Untracked properties are not re-rendered in the UI when they change
• Untracked properties that are bound to inputs are not automatically updated when the input changes unless there is an onchange handler defined that updates the Javascript property

A single untracked property

Testing with a simple component that contains a single property that is tracked, I found the following behaviour:

Javascript component

    export default class TrackExperiments extends LightningElement {
        @track primitiveTracked;

        handlePrimitiveTrackChanged( event ) {
            this.primitiveTracked = event.target.value;
        }
    }

Template

    <p>The value is: {primitiveTracked}</p>
    <lightning-input label="Input without an on-change handler"
                        type="Text"
                        value={primitiveTracked}></lightning-input>
    <lightning-input label="Input with an on-change handler"
                        type="Text" value={primitiveTracked}
                        onchange={handlePrimitiveTrackChanged}></lightning-input>

• Whenever the value of the Javascript property changes, it is reflected on the outputted page.
• Changing the value defined in the input without the onchange handler will not change the Javascript property, and so the rendered property does not change.
• Changing the value defined in the input that does have an onchange handler will update the Javascript property, and both the rendered property and the value in the other input is updated.

OK, in my opinion, slightly odd - I was expecting the input binding to be two-way - that's not the case:

Lightning Web Components contain 1-way binding.

Still, it may have surprised me, but it's easy to remember, and no big deal once you know that's the behaviour.

• Tracked properties are re-rendered in the UI when they change.
• Tracked properties that are bound to inputs are not automatically updated when the input changes unless there is an onchange handler defined that updates the Javascript property.
• Inputs that are bound to tracked properties are automatically updated when the underlying property is updated.

A tracked property and an untracked property on the same page

Javascript component

    export default class TrackExperiments extends LightningElement {
        @track primitiveTracked;
        primitiveUntracked;

        handlePrimitiveTrackChanged( event ) {
            this.primitiveTracked = event.target.value;
        }

        handlePrimitiveUntrackChanged( event ) {
            this.primitiveUntracked = event.target.value;
        }
}

Template

    <p>The value is: {primitiveTracked}</p>
    <lightning-input label="Input without an on-change handler"
                        type="Text"
                        value={primitiveTracked}></lightning-input>
    <lightning-input label="Input with an on-change handler"
                        type="Text" value={primitiveTracked}
                        onchange={handlePrimitiveTrackChanged}></lightning-input>

    <p>The value is: {primitiveUntracked}</p>
    <lightning-input label="Input without an on-change handler"
                        type="Text"
                        value={primitiveUntracked}></lightning-input>
    <lightning-input label="Input with an on-change handler"
                        type="Text"
                        value={primitiveUntracked}
                        onchange={handlePrimitiveUntrackChanged}></lightning-input>

Now things start to get a little surprising.

• Changing the inputs related to the tracked property works as described above, as if it was the only property on page.
• Then, changing the inputs related to the untracked property as described above.
• However, changing the tracked property inputs after changing the untracked input, causes both the tracked and untracked properties to be re-rendered.

The last point really took me by surprise - I was expecting that only the tracked property would be updated. This led me to go back to the documentation again and re-read it.

That is (bold added for emphasis):

Both @track and @api mark a property as reactive. If the property’s value changes, the component rerenders.

Yep, I think I'm reading that right, and it looks like it's reflected in the behaviour I see (without delving too deep into it). When you change the value of a tracked property, the whole component re-renders. This means that any untracked properties will also be re-rendered.

I've put together a more complete illustration of that, which you can find in this git repo.