Utility Bar API

This component allows you to access methods for programmatically controlling a utility within the utility bar of a Lightning app. The utility bar is a footer that gives users quick access to frequently used tools and components. Each utility is a single-column Lightning page that includes a standard or custom Lightning component.

To access the methods, create an instance of the lightning:utilityBarAPI component inside of your utility and assign an aura:id attribute to it.

1<lightning:utilityBarAPI aura:id="utilitybar" />

This example sets the icon of a utility to the SLDS “insert tag field” icon when the button is clicked.

1<aura:component implements="flexipage:availableForAllPageTypes" access="global">
2  <lightning:utilityBarAPI aura:id="utilitybar" />
3  <lightning:button label="Set Utility Icon" onclick="{! c.setUtilityIcon }" />
4</aura:component>

The button in the component calls the following client-side controller.

1({
2  setUtilityIcon: function (component, event, helper) {
3    var utilityAPI = component.find("utilitybar");
4    utilityAPI.setUtilityIcon({ icon: "insert_tag_field" });
5  },
6});

This component supports the following methods. Most methods take only one argument, a JSON array of parameters. The utilityId parameter is only optional if within a utility itself. For more information on these methods, see the Console Developer Guide.

getEnclosingUtilityId()

Returns a Promise. Success resolves to the enclosing utilityId or false if not within a utility. The Promise will be rejected on error.

getUtilityInfo({utilityId})

• utilityId (string): Optional. The ID of the utility for which to get info.

Returns a Promise. Success resolves to a utilityInfo object. The Promise will be rejected on error.

getAllUtilityInfo()

Returns a Promise. Success resolves to an array of utilityInfo objects. The Promise will be rejected on error.

minimizeUtility({utilityId})

• utilityId (string): Optional. The ID of the utility for which to minimize.

Returns a Promise. Success resolves to true. The Promise will be rejected on error.

onUtilityClick({utilityId, eventHandler})

• utilityId (string): Optional. The ID of the utility for which to register the callback.
• eventHandler (function): The JavaScript function that’s called when the utility is clicked.

Returns a Promise. Success resolves to true. The Promise will be rejected on error.

openUtility({utilityId})

• utilityId (string): Optional. The ID of the utility for which to open.

Returns a Promise. Success resolves to true. The Promise will be rejected on error.

setPanelHeaderIcon({icon, utilityId})

• icon (string): An SLDS utility icon key. This is displayed in the utility panel. See a full list of utility icon keys on the SLDS reference site.
• utilityId (string): Optional. The ID of the utility for which to set the panel header icon on.

Returns a Promise. Success resolves to true. The Promise will be rejected on error.

setPanelHeaderLabel({label, utilityId})

• label (string): The label of the utility displayed in the panel header.
• utilityId (string): Optional. The ID of the utility for which to set the panel header label on.

Returns a Promise. Success resolves to true. The Promise will be rejected on error.

setPanelHeight({heightPX, utilityId})

• heightPX (integer): The height of the utility panel in pixels.
• utilityId (string): Optional. The ID of the utility for which to set the panel height on.
• durationMs (number): Optional. The time in milliseconds it takes for the height transition to complete. Default value is 0.
• timingFunction (string): Optional. The transition timing function that sets the rate for panel height changes. Supports any CSS easing function supported by your target browser. Default value is ease.
• delayMs (number): Optional. The wait time in milliseconds before the height transition starts. Default value is 0.

Returns a Promise. Success resolves to true. The Promise will be rejected on error.

setPanelWidth({widthPX, utilityId})

• widthPX (integer): The width of the utility panel in pixels.
• utilityId (string): Optional. The ID of the utility for which to set the panel width on.
• durationMs (number): Optional. The time in milliseconds it takes for the width transition to complete. Default value is 0.
• timingFunction (string): Optional. The transition timing function that sets the rate for panel height changes. Supports any CSS easing function supported by your target browser. Default value is ease.
• delayMs (number): Optional. The wait time in milliseconds before the height transition starts. Default value is 0.

Returns a Promise. Success resolves to true. The Promise will be rejected on error.

disableUtilityPopOut({disabled, disabledText})

• disabled (boolean): Whether the pop-out and pop-in options are disabled. Set to true to disable pop-out or pop-in for the utility item.
• disabledText (string): Optional. Used as the hover text and alternative text for the pop-in or pop-out option.

Returns a Promise. Success resolves to true. The Promise will be rejected on error.

setUtilityHighlighted({highlighted, utilityId})

• highlighted (boolean): Whether the utility is highlighted. Makes a utility more prominent by giving it a different background color.
• utilityId (string): Optional. The ID of the utility for which to set highlighted.

Returns a Promise. Success resolves to true. The Promise will be rejected on error.

setUtilityIcon({icon, utilityId})

• icon (string): An SLDS utility icon key. This is displayed in the utility bar. See a full list of utility icon keys on the SLDS reference site.
• utilityId (string): Optional. The ID of the utility for which to set the icon on.

Returns a Promise. Success resolves to true. The Promise will be rejected on error.

setUtilityLabel({label, utilityId})

• label (string): The label of the utility. This is displayed in the utility bar.
• utilityId (string): Optional. The ID of the utility for which to set the label on.

Returns a Promise. Success resolves to true. The Promise will be rejected on error.

toggleModalMode({enableModalMode, utilityId})

• enableModalMode (boolean): Whether to enable the utility’s modal mode. While in modal mode, an overlay is shown over the whole app that blocks usage while the utility panel is still visible.
• utilityId (string): Optional. The ID of the utility for which to toggle modal mode.

Returns a Promise. Success resolves to true. The Promise will be rejected on error.

isUtilityPoppedOut()

Returns a Promise. Resolves to true if utility is in a popped out window, false otherwise. Promise will be rejected on an error.