Data Flow

To prevent code complexity and unexpected side effects, data should flow in one direction, from parent to child.

When a component decorates a field with @api to expose it as a public property, it should set the value only when it initializes the field. After the field is initialized, only the owner component should set the value. A component should treat values passed to it as read-only. To trigger a mutation for a property value provided by an owner component, a child component can send an event to the parent. If the parent owns the data, the parent can change the property value, which propagates down to the child component via the one-way data binding.

A non-primitive value (like an object or array) passed to a component is read-only. The component cannot change the content of the object or array. If the component tries to change the content, you see an error in the browser console. To mutate the data, make a shallow copy of the objects you want to mutate.

To trigger a mutation for a property value provided by an owner component, a component should send an event to the owner.

To understand read-only objects, read the docs and play with the code at lwc.dev, which is the Lightning Web Components: Open Source developer site.

We recommend using primitive data types for properties instead of using object data types. Slice complex data structures in a higher-level component and pass the primitive values to the component descendants.

There are a few reasons that it’s better to use primitive values.

  • Primitive values require specific @api properties that clearly define the data shape. Accepting an object or an array requires documentation to specify the shape. If an object shape changes, consumers break.
  • Standard HTML elements accept only primitive values for attributes. When a standard HTML element needs a complex shape, it uses child components. For example, a table element uses tr and td elements. Only primitive types can be defined in HTML. For example, <table data={...}> isn't a value in HTML, only in Lightning Web Components.