Migrate Events

Migrate component events in Aura components to standard DOM events in Lightning web components.

Here’s an overview for working with events in Lightning web components.

Create an event

Instead of the proprietary Event object in Aura components, use the Event or CustomEvent standard DOM objects. There's no equivalent in Lightning web components for the <aura:registerEvent> tag in Aura component markup to register that a component can fire an event.

Fire an event

Instead of event.fire() in an Aura component, use this.dispatchEvent(myEvent), which is a standard DOM method, in Lightning web components.

Handle an event

An Aura component uses the <aura:handler> tag in markup to define a handler. Alternatively a component can declare a handler action when it references another component in its markup. This Aura component uses c:child in its markup and declares a handleChildEvent handler for the sampleComponentEvent that c:child fires.

A Lightning web component can similarly declare a declarative handler. The event name in the declarative handler is prefixed by on.

<!-- prettier-ignore -->

The event handler function, handleChildEvent, is defined in the JavaScript file of the component.

In a Lightning web component, you can also programmatically set up a handler using the standard addEventListener() method in the component's JavaScript file.

Retrieve an event payload

Use the event.detail property to retrieve the event payload unless otherwise stated.

Use the Lightning message service (lightning/messageService) to communicate with components within a single page or across multiple pages. You can also use the pub-sub pattern to communicate between components within a single page.

This table maps standard Aura events, such as for navigating to a component or to display the record create panel, to usage in Lightning web components. Events that are not listed don’t currently have an equivalent in Lightning Web Components.

Aura ComponentLightning Web ComponentDescription
aura:locationChangeThe hashchange browser event fires when a window's hash changes. To handle this event, use the onhashchange event handler.Fired when the hash part of the URL in the browser's location bar has been modified.
aura:valueChangeUse properties with custom getter and setter methods.Fired when a property value has changed.
aura:valueDestroyUse the disconnectedCallback() lifecycle hook. See Component Lifecycle.Fired when a component is destroyed.
aura:valueInitTo replace the init event handler, use the connectedCallback() lifecycle hook. See Migrate Initializers.Fired when a component has been initialized.
aura:valueRenderUse the renderedCallback() or render() lifecycle hook. See Component Lifecycle.Fired when a component has been rendered.
force:createRecordUse the navigation service.Displays the record create panel.
force:editRecordUse the navigation service.Displays the record edit panel.
force:navigateHome (deprecated)Use the navigation service.Navigates to a record home page.
force:navigateToComponent (deprecated)Use the navigation service.Navigates to a component.
force:navigateToListUse the navigation service.Navigates to a list view.
force:navigateToObjectHomeUse the navigation service.Navigates to an object home page.
force:navigateToRelatedListUse the navigation service.Navigates to a related list.
force:navigateToSObjectUse the navigation service.Navigates to a record.
force:navigateToURLUse the navigation service.Navigates to a URL.
force:refreshViewUse the RefreshView API.Reloads the view without a page reload.
force:showToastImport the lightning/platformShowToastEvent module. See Toast NotificationsDisplays a toast message to alert users of a success, error, or warning.
lightning:openFilesUse the navigation service. See Open Files.Opens one or more file records.
lightning:tabClosedUse the lightning__tabClosed Lightning message channel.Fires when a Console workspace or subtab has been successfully closed.
lightning:tabCreatedUse the lightning__tabCreated Lightning message channel.Fires when a Console workspace or subtab has been successfully created.
lightning:tabFocusedUse the lightning__tabFocused Lightning message channel.Fires when a Console workspace or subtab is focused.
lightning:tabRefreshedUse the lightning__tabRefreshed Lightning message channel.Fires when a Console workspace or subtab has been successfully refreshed.
lightning:tabReplacedUse the lightning__tabReplaced Lightning message channel.Fires when a Console primary tab or subtab has been successfully replaced.
lightning:tabUpdatedUse the lightning__tabUpdated Lightning message channel.Fires when a Console workspace or subtab has been updated, which includes label, icon, or other content changes.
ltng:afterScriptsLoadedImport the static resource and import methods from the lightning/platformResourceLoader module. See Use Third-Party JavaScript Libraries.Fired when ltng:require has loaded all scripts listed in ltng:require.scripts

See Also