Spread Properties on Child Components

Pass a set of properties in an object to a child component using the lwc:spread directive. lwc:spread also enables elements to accept an object that’s bound as properties at runtime.

You don’t have to manually define each attribute or property in your template like this.

1<!-- Replace this with lwc:spread -->
2<c-mycomponent name={config.name} country={config.country}></c-mycomponent>

lwc:spread makes it easier to work with large config or objects. You can dynamically pass multiple attributes or properties. However, it only spreads top-level properties. Nested objects won’t be automatically spread.

The lwc-recipes repo has an apiSpread component that demonstrates the lwc:spread directive.

Tip

The lwc:spread directive accepts one object.

1<!-- app.html -->
2<template>
3  <c-child lwc:spread={childProps}></c-child>
4</template>

Use an object with key-value pairs, where the keys are property names.

1// app.js
2import { LightningElement } from "lwc";
3
4export default class extends LightningElement {
5  childProps = { name: "James Smith", country: "USA" };
6}

In your child component, use the properties in your template.

1<!-- child.html -->
2<template>
3  <p>Name: {name}</p>
4  <p>Country : {country}</p>
5</template>

Use the @api decorator to expose your properties to the parent component.

1// child.js
2import { LightningElement, api } from "lwc";
3
4export default class Child extends LightningElement {
5  @api name;
6  @api country;
7}

lwc:spread is always applied last, so it overrides any properties that are directly declared in the template. Only one lwc:spread instance can be used on a directive.

1<!-- app.html -->
2<template>
3  <c-child name="lwc" lwc:spread={childProps}></c-child>
4</template>

In this example, c-child passes name as Lightning Web Components even though the parent component is passing in name="lwc". Ultimately, the child component takes the "Lightning Web Components" name.

1// app.js
2import { LightningElement } from "lwc";
3
4export default class extends LightningElement {
5  childProps = { name: "Lightning Web Components" };
6}

Use lwc:spread With an Event Handler

lwc:spread doesn’t bind the component to the event handlers defined in the template. For example, you can pass in an onclick handler in the object as the property name.

1<!-- app.html -->
2<template>
3  <c-child lwc:spread={simpleProps}></c-child>
4</template>

Here, c-child passes name as LWC. When the c-child element is clicked, spreadClick() replaces name with Lightning Web Components.

1// app.js
2import { LightningElement } from "lwc";
3
4export default class extends LightningElement {
5  simpleProps = { name: "LWC", onclick: this.spreadClick.bind(this) };
6  spreadClick() {
7    this.simpleProps = { name: "Lightning Web Components" };
8  }
9}

Although we don’t include onclick in spreadClick(), the element contains onclick as previously assigned to it via the simpleProps object.

Reflect HTML Attributes on a Child Component

Most of the HTML attributes are reflected as properties. For example, class attribute is reflected as className property.

Let’s say you pass properties to a child component.

1<!-- app.html -->
2<template>
3  <c-child lwc:spread={spanProps}></c-child>
4</template>

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

1// app.js
2import { LightningElement } from "lwc";
3
4export default class extends LightningElement {
5  spanProps = { className: "spanclass", id: "myspan" };
6}

See Also

Release Preview

This release is in preview. Features described here don't become generally available until the latest general availability date that Salesforce announces for this release. Before then, and where features are noted as beta, pilot, or developer preview, we can't guarantee general availability within any particular time frame or at all. Make your purchase decisions only on the basis of generally available products and features.