setTabHighlighted() for Lightning Experience

Highlights the specified tab with a different background color and a badge. Tab highlights don’t persist after reloading a Lightning console app. This method works only in Lightning console apps.

Arguments

Name	Type	Description
`tabId`	string	The ID of the tab to be highlighted.
`highlighted`	boolean	Whether the tab is highlighted. Makes a utility more prominent by giving it a different background color.
`options`	object	Optional. Additional options that modify the appearance of the highlighted tab. Available options are: `pulse`: If true, causes two colors to alternate in a smooth animation. `state`: Changes the tab color. Available types are `success` (), `warning` (), and `error` ().

LWC Sample Code

This component checks if it’s in a Lightning console app, returns information about the focused tab and highlights it in green.

1import { LightningElement, wire } from 'lwc';
2import {
3    IsConsoleNavigation,
4    getFocusedTabInfo,
5    setTabHighlighted
6} from 'lightning/platformWorkspaceApi';
7
8export default class WorkspaceAPIHighlightTab extends LightningElement {
9    @wire(IsConsoleNavigation) isConsoleNavigation;
10
11    async highlightTab(event) {
12        if (!this.isConsoleNavigation) {
13            return;
14        }
15        const highlighted = event.detail.checked;
16        const { tabId } = await getFocusedTabInfo();
17        setTabHighlighted(tabId, highlighted, {
18            pulse: true,
19            state: 'success'
20        });
21    }
22}

This example is the workspaceAPIHighlightTab component from the lwc-recipes repo.

To make your component available for use in a Lightning console app, specify the lightning__AppPage target in the component’s configuration file.

Aura Components Sample Code

This component has a button that, when pressed, sets the focused tab as highlighted.

Component code:

1<aura:component implements="flexipage:availableForAllPageTypes" access="global" >
2    <lightning:workspaceAPI aura:id="workspace" />
3    <lightning:button label="Set Focused Tab Highlighted" onclick="{! c.setFocusedTabHighlighted }" />
4</aura:component>

Controller code:

1({
2    setFocusedTabHighlighted : function(component, event, helper) {
3        var workspaceAPI = component.find("workspace");
4        workspaceAPI.getFocusedTabInfo().then(function(response) {
5            var focusedTabId = response.tabId;
6            workspaceAPI.setTabHighlighted({
7                tabId: focusedTabId,
8                highlighted: true,
9                options: {
10                    pulse: true,
11                    state: "success"
12         }
13            });
14        })
15        .catch(function(error) {
16            console.log(error);
17        });
18    }
19})

Response

This method returns a promise that, upon success, returns a tabInfo object representing the modified tab. A tabInfo object is a JSON array of information about a workspace tab, with nested arrays of information on each subtab. This is the structure of a tabInfo object.

1{
2     tabId: string,
3     url: string (URL),
4     pinned: boolean,
5     closeable: boolean,
6     title: string,
7     icon: string (SLDS iconKey),
8     iconAlt: string,
9     customTitle: string (optional),
10     customIcon: string (optional),
11     customIconAlt: string (optional),
12     highlighted: boolean,
13     pageReference: object,
14     isSubtab: boolean,
15     parentTabId: string,
16     subtabs: [
17         {
18             tabId: string,
19             url: string (URL),
20             pinned: boolean,
21             closeable: boolean,
22             title: string,
23             icon: string (SLDS iconKey),
24             iconAlt: string,
25             customTitle: string (optional),
26             customIcon: string (optional),
27             customIconAlt: string (optional),
28             highlighted: boolean,
29             pageReference: object,
30             isSubtab: boolean,
31             parentTabId: string,
32             focused: boolean,
33             recordId: string,
34          },
35           ... 
36     ],
37     focused: boolean,
38     recordId: string
39}