Does StencilJS re-render a component when an @Prop object or array is mutated in place?

Short answer

No. StencilJS does not re-render a component when an @Prop object or array is mutated in place without changing the reference. An unchanged object or array reference is treated as a non-change, so array.push, array.splice, or nested property assignment will not schedule a child re-render by itself.

Likely explanation versus confirmed behavior

Likely explanation: Stencil compares the incoming prop reference against the previous reference. Because in-place mutation preserves the same reference, the comparison detects no difference and skips rendering.

Behavior in current stable Stencil releases:

• @Prop values are compared by shallow reference.
• In-place mutations keep the same reference and do not trigger a re-render.
• Reassigning the prop to a new array or object reference changes the comparison result and triggers a re-render.
• @Prop({ mutable: true }) only permits the component to mutate the value; it does not enable deep change detection.
• There is no built-in deep watch for nested @Prop changes.

Assumptions and uncertainty

This behavior is consistent across recent major Stencil versions. I have not fetched version-specific release notes, so if you are using a pre-release or very old version, check your installed version's documentation before relying on this.

Steps for this case

1. In the parent, replace the reference instead of mutating in place:

const nextItems = [...items, newItem];
setItems(nextItems);

1. For nested objects, spread into a new object:

const nextConfig = { ...config, theme: 'dark' };
setConfig(nextConfig);

1. If the component owns the mutable data, use @State instead of @Prop; Stencil re-renders when @State is assigned.
2. If you must mutate an existing @Prop({ mutable: true }) reference, call this.requestUpdate() after the mutation to force a render.

Verification

• Add console.log('render') inside the child component's render() method.
• Push to the parent array without reassigning it and confirm the log does not fire.
• Reassign the prop to a new array reference and confirm the log fires.

One missing diagnostic detail that changes the recommendation: are the mutations happening in the parent or in the child? Parent mutations usually require a new reference from the parent; child-owned mutations are better handled with @State.