Message Service
lightning/messageService
Enables communication across different types of pages.
For Use In
Lightning Experience, Experience Builder Sites, Salesforce Mobile App
Use Lightning message service to communicate across the DOM between Visualforce pages, Aura components, and Lightning web components, including components in a pop-out utility bar.
Use the Lightning message service functions to communicate over a Lightning message channel.
In a component's Javascript file, import the functions you need from the lightning/messageService module. Import a message channel using the scoped module @salesforce/messageChannel.
Returns a MessageContext object.
Call this function in a service component that doesn't extend LightningElement. In a service component, you can’t use @wire(MessageContext) to create a MessageContext object. Instead, call the createMessageContext() function to create the MessageContext object and assign it to a field, like messageContext. Then, pass messageContext into the subscribe() function. MessageContext isn’t automatically released for service components. Call releaseMessageContext(messageContext) to remove any subscriptions associated with your Lightning web component’s MessageContext.
Publishes a message to a specified message channel.
| Parameter | Type | Description |
|---|---|---|
messageContext | object | The MessageContext object provides information about the Lightning web component that is using the Lightning message service. Get this object via the MessageContext wire adapter or via createMessageContext(). |
messageChannel | object | The message channel object. To import a message channel, use the scoped module @salesforce/messageChannel. To create a message channel in an org, use the LightningMessageChannel metadata type. |
message | object | A serializable JSON object containing the message published to subscribers. A message can't contain functions or symbols. |
Releases a MessageContext object associated with a Lightning web component and unsubscribes all associated subscriptions.
Subscribes to a specified message channel. Returns a Subscription object that you can use to unsubscribe.
By default, communication over a message channel can occur only between Lightning web components, Aura components, or Visualforce pages in an active navigation tab, an active navigation item, or a utility item. Utility items are always active. A navigation tab or item is active when it’s selected. Navigation tabs and items include:
- Standard navigation tabs
- Console navigation workspace tabs
- Console navigation subtabs
- Console navigation items
To receive messages on a message channel from anywhere in the application, pass the subscriberOptions parameter as {scope: APPLICATION_SCOPE}. Import APPLICATION_SCOPE from lightning/messageService.
| Parameter | Type | Description |
|---|---|---|
messageContext | object | The MessageContext object provides information about the Lightning web component that is using the Lightning message service. |
messageChannel | object | To import a message channel, use the scoped module @salesforce/messageChannel. To create a message channel in an org, use the LightningMessageChannel metadata type. |
listener | function | A function that handles the message once it is published. |
subscriberOptions | object | (Optional) An object that, when set to {scope: APPLICATION_SCOPE}, specifies the ability to receive messages on a message channel from anywhere in the application. Import APPLICATION_SCOPE from lightning/messageService. |
Unsubscribes from a message channel.
| Parameter | Type | Description |
|---|---|---|
subscription | object | The Subscription object returned by the subscribe() function. |
Returns a MessageContext object.
The MessageContext object contains information about the Lightning web component that is using the Lightning message service. Pass the MessageContext object to the publish() and subscribe() functions. When using the @wire(MessageContext) adapter, you don’t have to interact with any of the component’s lifecycle events. The Lightning message service features automatically unregister when the component is destroyed.
These two components publish a message and subscribe to the message over the same message channel.
The LWC Recipes GitHub repository contains code examples for Lightning Web Components that you can test in an org.
For a recipe that uses lightning/messageService, see the following components in the LWC Recipes repo.
c-lms-publisher-web-componentc-lms-subscriber-web-component
Lightning Web Components Developer Guide: Communicate Across the DOM with Lightning Message Service