Enable reactivity in lwc:spread (LWC)

With the introduction of Salesforce Summer '23 release, a new feature for LWC components called lwc:spread became available. This feature enables us to spread properties on child components. Although the documentation provides instructions on its usage, ensuring the spread feature's reactivity is essential to fully leverage its capabilities. In this article, we will delve into examples of a parent component and a nested child component to grasp how to achieve reactivity for maximum usability.

The lwc:spread directive allows accepting a single object with key-value pairs, where the keys represent property names. In the example below, we demonstrate how to use this feature to spread properties on child components:

<!-- app.html -->

<template>

    <c-child lwc:spread={childProps}></c-child>

</template>

In this case, the parent component sets an object called "childProps" with properties "name" and "country" having values 'James Smith' and 'USA' respectively.

// app.js

import { LightningElement } from 'lwc';

export default class extends LightningElement {

childProps = { name: 'James Smith', country: 'USA' };

}

The child component, "c-child," utilizes these properties within its template:

<!-- child.html -->

<template>

  <p>Name: {name}</p>

  <p>Country : {country} </p>

</template>

To expose the properties to the parent component, we use the @api decorator:

// child.js

import { LightningElement, api } from 'lwc';

export default class Child extends LightningElement {

@api name;

@api country;

}

One important thing to note is that lwc:spread is always applied last and will override any directly declared properties in the template. Only one lwc:spread instance can be used on a directive.

<!-- app.html -->

<template>

  <c-child name="lwc" lwc:spread={childProps}></c-child>

</template>

In this example, even though the parent component sets "name" as "LWC," the child component receives "name" as "Lightning Web Components" due to the spread functionality.

Additionally, it's crucial to know that lwc:spread doesn't bind the component to event handlers defined in the template. For instance, you can pass an onclick handler as a property in the object.

<!-- app.html -->

<template>

    <c-child lwc:spread={simpleProps}></c-child>

</template>

Here, the "c-child" component receives "name" as "LWC." When the "c-child" element is clicked, "spreadClick()" updates "name" to "Lightning Web Components."

// app.js

import { LightningElement } from 'lwc';

export default class extends LightningElement {

simpleProps = { name: "LWC", onclick: this.spreadClick.bind(this) };

spreadClick() {

this.simpleProps = { name: "Lightning Web Components" };

}

}

Remember that although we don't include onclick in spreadClick(), the element retains the onclick behavior as previously assigned via the simpleProps object.

Lastly, HTML attributes on a child component are mostly reflected as properties. For instance, the class attribute is reflected as the className property.

For example:

<!-- app.html -->

<template>

    <c-child lwc:spread={spanProps}></c-child>

</template>

The spanProps property causes the "c-child" element to be rendered as <c-child class="spanclass" id="mySpan"></c-child>.

// app.js

import { LightningElement } from 'lwc';

export default class extends LightningElement {

spanProps = { className: 'spanclass', id: 'myspan' };

}

Reactivity Challenge:

you'll notice that the className and i in the child component won't be re-rendered as they would with the regular parameter passing approach. The provided documentation offers an example where we can modify the name, but it requires completely assigning another object to the same variable.

Here's the static approach presented in the documentation:

spanProps = { className: 'spanclass', id: 'myspan' };

{

    this.spanProps.className = 'childProps123235';

    this.spanProps.id = 9876;

    this.spanProps = {...this.spanProps};

}

However, this static approach lacks the dynamic flexibility that developers might seek when changing parameters.

Findings:

We begin with the example provided by Salesforce, which at least works, and then attempt to modify it:

{

    this.spanProps = {};

    this.spanProps.className = 'childProps12355';

    this.spanProps.id = 9876;

}

While this solution does work, it may not be suitable if spanProps already contains important information.

An alternative approach involves using a temporary variable:

{

    const a = {...this.spanProps};

    a.className = 'ABCD';

    this.spanProps = a;

}

In both cases, the property is re-rendered on the component. By comparing this with the earlier example that didn't work, we can see that it's essential to put the reassignment first before any data manipulations or use destructuring reassignment with the required parameters.

However, it's important to note that some reliable methods like Object.assign or JSON.parse(JSON.stringify(obj)) do not work:

This behavior is not adequately described in the documentation, resulting in inconsistency. To make the spread operator reactive, developers must be aware of these rules. Hopefully, it will be addressed or better explained in the near future since this feature is truly beneficial and can efficiently manage child component parameters.

Conclusion:

Reactivity plays a crucial role when utilizing the lwc:spread feature in LWC components. Although there are workarounds to achieve reactivity, the behavior and rules are not explicitly documented. By understanding the correct approaches, developers can fully leverage the power of lwc:spread to enhance the management of child component parameters.

Happy coding, everyone!