Lightning Aura Components Developer Guide

Introducing Aura Components
Quick Start
Creating Components
Using Components
Communicating with Events
Actions and Events
Handling Events with Client-Side Controllers
Component Events
Application Events
Application Event Propagation
Create Custom Application Events
Fire Application Events
Handling Application Events
Application Event Example
Event Handler Behavior for Active Components
Event Handling Lifecycle
Advanced Events Example
Firing Events from Non-Aura Code
Events Best Practices
Events Fired During the Rendering Lifecycle
Events Handled in the Salesforce Mobile App and Lightning Experience
System Events
Communicating Across the DOM with Lightning Message Service
Creating Apps
Styling Apps
Developing Secure Code
Using JavaScript
Working with Salesforce Data
Testing Components
Debugging
Performance
Reference
PDF

Application Event Propagation

The framework supports capture, bubble, and default phases for the propagation of application events. The capture and bubble phases are similar to DOM handling patterns and provide an opportunity for interested components to interact with an event and potentially control the behavior for subsequent handlers. The default phase preserves the framework’s original handling behavior.

A component can publish an application-level event. When the event is fired, any component or application that has subscribed to the event invokes its handler within a Lightning page. To communicate across the DOM within a Lightning page, or across multiple pages between Visualforce, Lightning pages, and Lightning web components (LWC), use Lightning Message Service instead.

The component that fires an event is known as the source component. The framework allows you to handle the event in different phases. These phases give you flexibility for how to best process the event for your application.

The phases are:

Capture

The event is captured and trickles down from the application root to the source component. The event can be handled by a component in the containment hierarchy that receives the captured event.

Event handlers are invoked in order from the application root down to the source component that fired the event.

Any registered handler in this phase can stop the event from propagating, at which point no more handlers are called in this phase or the bubble phase. If a component stops the event propagation using event.stopPropagation(), the component becomes the root node used in the default phase.

Any registered handler in this phase can cancel the default behavior of the event by calling event.preventDefault(). This call prevents execution of any of the handlers in the default phase.

Bubble

The component that fired the event can handle it. The event then bubbles up from the source component to the application root. The event can be handled by a component in the containment hierarchy that receives the bubbled event.

Event handlers are invoked in order from the source component that fired the event up to the application root.

Any registered handler in this phase can stop the event from propagating, at which point no more handlers will be called in this phase. If a component stops the event propagation using event.stopPropagation(), the component becomes the root node used in the default phase.

Any registered handler in this phase can cancel the default behavior of the event by calling event.preventDefault(). This call prevents execution of any of the handlers in the default phase.

Default

Event handlers are invoked in a non-deterministic order from the root node through its subtree. The default phase doesn’t have the same propagation rules related to component hierarchy as the capture and bubble phases. The default phase can be useful for handling application events that affect components in different sub-trees of your app.

If the event’s propagation wasn’t stopped in a previous phase, the root node defaults to the application root. If the event’s propagation was stopped in a previous phase, the root node is set to the component whose handler invoked event.stopPropagation().

Here is the sequence of application event propagation.