Utility Bar API

lightning:utilityBarApi

Work with a utility within the utility bar of a Lightning app.

For Aura components only. For LWC development, use lightning/platformUtilityBarApi.

For Use In

Lightning Experience

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 attribute to it.

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

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

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.