Component Events

Create Custom Component Event

You can create custom component events using the <aura:event> tag in a .evt resource. Events can contain attributes that can be set before the event is fired and read when the event is handled.

Use type="COMPONENT" in the <aura:event> tag for a component event. For example, this is a docsample:compEvent component event with one message attribute.

1<!--docsample:compEvent-->
2<aura:event type="COMPONENT">
3    <!-- add aura:attribute tags to define event shape.
4      One sample attribute here -->
5    <aura:attribute name="message" type="String"/>
6</aura:event>

The component that handles an event can retrieve the event data. To retrieve the attribute in this event, call event.getParam("message") in the handler’s client-side controller.

Register Component Event

A component registers that it may fire an event by using <aura:registerEvent> in its markup. For example:

1<aura:registerEvent name="sampleComponentEvent" type="docsample:compEvent"/>

We’ll see how the value of the name attribute is used for firing and handling events.

Fire Component Event

To get a reference to a component event in JavaScript, use getEvent("evtName") where evtName matches the name attribute in <aura:registerEvent>. Use fire() to fire the event from an instance of a component. For example, in an action function in a client-side controller:

1var compEvent = cmp.getEvent("sampleComponentEvent");
2// set some data for the event (also known as event shape)
3// compEvent.setParams(...);
4compEvent.fire();

Component Handling Its Own Event

A component can handle its own event by using the aura:handler tag in its markup.

The action attribute of <aura:handler> sets the client-side controller action to handle the event. For example:

1<aura:registerEvent name="sampleComponentEvent" type="docsample:compEvent"/>
2<aura:handler name="sampleComponentEvent" action="{!c.handleSampleEvent}"/>

Handle Component Event of Instantiated Component

The component that registers an event declares the name attribute of the event. For example, an <docsample:eventsNotifier> component contains a <aura:registerEvent> tag.

1<aura:registerEvent name="sampleComponentEvent" type="docsample:compEvent"/>

When you instantiate <docsample:eventsNotifier> in another component, use the value of the name attribute from the <aura:registerEvent> tag to register the handler. For example, if an <docsample:eventsHandler> component includes <docsample:eventsNotifier> in its markup, eventsHandler instantiates eventsNotifier and can handle any events thrown by eventsNotifier. Here’s how <docsample:eventsHandler> instantiates <docsample:eventsNotifier>:

1<docsample:eventsNotifier sampleComponentEvent="{!c.handleComponentEventFired}"/>

Note how sampleComponentEvent matches the value of the name attribute in the <aura:registerEvent> tag in <docsample:eventsNotifier>.

Handle Component Event Dynamically

A component can have its handler bound dynamically via JavaScript. This is useful if a component is created in JavaScript on the client-side. See Dynamically Adding Event Handlers.

Get the Source of a Component Event

Use evt.getSource() in JavaScript to find out which component fired the component event, where evt is a reference to the event.