onUtilityClick() for Lightning Experience

Consider the following guidelines when working with this method.

• The method is supported in Lightning apps with standard and console navigation.
• You can use this method to register multiple callbacks per utilityItem when executed sequentially.
• You can’t remove registered callbacks.

Arguments

The method provides the same arguments for both Aura Components and Lightning Web Components (LWC).

For LWC, optional parameters are passed into an object as the last argument of the method.

LWC Sample Code

This component handles a utility click using the EnclosingUtilityId wire adapter.

1import { LightningElement, wire } from 'lwc';
2import { onUtilityClick, EnclosingUtilityId } from 'lightning/platformUtilityBarApi';
3
4export default class UtilityClickExample extends LightningElement {
5    @wire(EnclosingUtilityId) utilityId;
6
7    handleUtilityClick() {
8        if (!this.utilityId) {
9            return;
10        }
11        onUtilityClick(this.utilityId, () => {
12            console.log(`Utility ${this.utilityId} clicked!`);
13        });
14    }
15}

To make your component available for use in a utility bar, specify the lightning__UtilityBar target in the component’s configuration file.

LWC Response

Returns a promise that resolves to true if successful. The promise is rejected on error.

Aura Components Sample Code

This component has a button that, when pressed, registers an eventHandler function for the enclosing utility.

Component code:

1<aura:component implements="flexipage:availableForAllPageTypes" access="global">
2    <lightning:utilityBarAPI aura:id="utilitybar" />
3    <lightning:button label="Register Event Handler" onclick="{!c.handleOnUtilityClick}"/>
4</aura:component>

Controller code:

1({
2  handleOnUtilityClick: function(component, event, helper){
3        var utilityBarAPI = component.find("utilitybar");
4	  var eventHandler = function(response){
5            console.log(response);
6        };
7        
8        utilityBarAPI.onUtilityClick({ 
9               eventHandler: eventHandler 
10        }).then(function(result){
11            console.log(result);
12        }).catch(function(error){
13        	console.log(error);
14        });
15    }
16})

Aura Components Response

This method returns a promise that, upon success, resolves to true, and is rejected on error. The eventHandler expects a response JSON object containing the following fields.