Triggering re-renders for nested object mutations in @State

The Solution: Manual Reference Reassignment

StencilJS does not provide a built-in mechanism for deep mutation tracking. The @State() decorator relies on strict reference equality (===) to detect changes. Because mutating a property inside a nested object does not change the object's memory address, Stencil will not trigger a re-render.

The most performant way to notify the framework of a change is through partial reference reassignment. Instead of cloning the entire state tree, you only replace the references along the path to the mutated property.

Implementation Pattern

Using the spread operator is the standard approach to create a new object reference while preserving the rest of the state:

@State() config = {
  region: 'US',
  settings: {
    theme: 'dark',
    notifications: true
  }
};

updateTheme(newTheme: string) {
  // Create new references for both the root object and the nested settings object
  this.config = {
    ...this.config,
    settings: {
      ...this.config.settings,
      theme: newTheme
    }
  };
}

Technical Explanation

When this.config is reassigned to a new object literal, Stencil's change detection identifies that the reference has changed and schedules a component re-render. By spreading ...this.config.settings, you ensure that other properties within the settings object are maintained without needing a full deep clone of the entire state tree.

Performance Considerations

• Avoid Deep Cloning: Do not use JSON.parse(JSON.stringify(obj)). This is computationally expensive and strips non-serializable data (like functions or Dates).
• Shallow Copying: Spreading only the modified branch minimizes memory overhead and keeps the update cycle efficient.
• State Splitting: If a nested object is updated frequently and independently, consider splitting it into multiple separate @State() variables to reduce the complexity of the reassignment logic.

To provide a more tailored recommendation, are you managing these nested objects within a single component, or are they passed down as props to child components?