onUtilityClick() for Lightning Experience

Registers an eventHandler for the utility. This eventHandler is called when the utility is clicked.

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.

Name	Type	Description
`utilityId`	string	The ID of the utility for which to register the callback. Optional when called within a utility using Aura Components. Always required for LWC.
`eventHandler`	function	The JavaScript function that’s called when the utility is clicked.

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.

Name	Type	Description
`utilityId`	string	The ID of the utilityBar item button that was clicked.
`panelVisible`	boolean	False if the utility item panel is hidden after the button is clicked. True if the utility item panel is visible after the button is clicked.