lightning:utilityBarAPI

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.

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.

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.

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.