Event Propagation: bubbles, composed, and Retargeting
By the end of this lesson, you'll be able to:
- Explain what the bubbles option controls on a CustomEvent
- Explain what the composed option controls on a CustomEvent
- Describe event retargeting across a Shadow DOM boundary
Prerequisites: "Child-to-Parent Communication with CustomEvent"
bubbles: Does the Event Travel Upward?
new CustomEvent('select', {
detail: this.contact.Id,
bubbles: true, // travels up through ancestor elements
});By default, bubbles is false — the event only reaches a direct listener on the exact element that dispatched it. Setting bubbles: true lets it travel upward through ancestor elements, the way a native click event does.
composed: Does the Event Cross the Shadow Boundary?
new CustomEvent('select', {
detail: this.contact.Id,
bubbles: true,
composed: true, // crosses out of this component's Shadow DOM
});By default, composed is also false — even a bubbling event stops at the edge of the component's Shadow DOM (Module 1). Setting composed: true lets it cross that boundary and continue bubbling into ancestor components outside.
Event Retargeting
When an event does cross a Shadow DOM boundary, its target gets retargeted — adjusted so listeners outside the component only see the component's own host element as the target, not its internal implementation details. This is deliberate: it preserves the encapsulation Module 1 introduced, even while allowing the event itself to propagate outward.
Why This Matters in Real Projects
"Why isn't my parent hearing this event?" is an extremely common real bug, and it almost always traces back to a missing bubbles: true or composed: true when the event actually needs to travel further than the immediate parent, or through a nested chain of components.
Exercise
A component two levels up the tree (a grandparent, not the direct parent) needs to hear this event. Which two options should be set to true?
Show hint
One controls upward travel through the DOM; the other controls crossing shadow boundaries.
Exercise
Challenge: explain, as a comment, why event retargeting matters for encapsulation, not just event delivery.
Show hint
Think about what an outside listener would otherwise be able to see.
Event Propagation: bubbles, composed, and Retargeting Quiz
My Notes
Log in to keep private notes on this lesson.
Questions about this lesson
No questions yet — be the first to ask.
Log in to ask a question about this lesson.
Summary
Two small constructor options — bubbles and composed — determine exactly how far a custom event actually travels, and getting them wrong is one of the most common "why isn't my parent hearing this event?" bugs.