Workspace API

The Workspace API allows Lightning Web Components to interact with the Salesforce console workspace, controlling tabs, subtabs, and navigation. This API is essential for building console applications that provide agent-friendly interfaces.

Workspace API methods only work in console applications. Always check if you’re in a console context using IsConsoleNavigation before calling Workspace API methods.

Checking Console Context

Before using any Workspace API methods, verify you’re in a console application:

import { LightningElement, wire } from 'lwc';
import { IsConsoleNavigation } from 'lightning/platformWorkspaceApi';

export default class MyComponent extends LightningElement {
    @wire(IsConsoleNavigation) isConsoleNavigation;

    async myMethod() {
        if (!this.isConsoleNavigation) {
            return;
        }
        // Safe to use Workspace API here
    }
}

Opening Tabs

Open new workspace tabs programmatically. workspaceAPIOpenTab.js:

import { LightningElement, wire } from 'lwc';
import { IsConsoleNavigation, openTab } from 'lightning/platformWorkspaceApi';

export default class WorkspaceAPIOpenTab extends LightningElement {
    @wire(IsConsoleNavigation) isConsoleNavigation;

    async openTab() {
        if (!this.isConsoleNavigation) {
            return;
        }

        // Open contact list in a new tab
        await openTab({
            pageReference: {
                type: 'standard__objectPage',
                attributes: {
                    objectApiName: 'Contact',
                    actionName: 'list'
                }
            },
            focus: true,
            label: 'Contacts List'
        });
    }
}

Opening Different Page Types

// Open a record page
await openTab({
    pageReference: {
        type: 'standard__recordPage',
        attributes: {
            recordId: '001xxxxxxxxxxxx',
            actionName: 'view'
        }
    },
    label: 'Account Record'
});

// Open a named page
await openTab({
    pageReference: {
        type: 'standard__namedPage',
        attributes: {
            pageName: 'home'
        }
    },
    label: 'Home'
});

// Open a Lightning component
await openTab({
    pageReference: {
        type: 'standard__component',
        attributes: {
            componentName: 'c__MyComponent'
        }
    },
    label: 'Custom Component'
});

Opening Subtabs

Open subtabs within a parent tab. workspaceAPIOpenSubtab.js:

import { LightningElement, wire } from 'lwc';
import {
    IsConsoleNavigation,
    getFocusedTabInfo,
    openSubtab
} from 'lightning/platformWorkspaceApi';

export default class WorkspaceAPIOpenSubtab extends LightningElement {
    @wire(IsConsoleNavigation) isConsoleNavigation;

    async openSubtab() {
        if (!this.isConsoleNavigation) {
            return;
        }

        // Get current parent tab
        const { tabId } = await getFocusedTabInfo();

        // Open a subtab
        await openSubtab(tabId, {
            pageReference: {
                type: 'standard__recordPage',
                attributes: {
                    recordId: '003xxxxxxxxxxxx',
                    actionName: 'view'
                }
            },
            focus: true
        });
    }
}

Setting Tab Label

Change the label of a tab dynamically. workspaceAPISetTabLabel.js:

import { LightningElement, wire } from 'lwc';
import {
    IsConsoleNavigation,
    getFocusedTabInfo,
    setTabLabel
} from 'lightning/platformWorkspaceApi';

export default class WorkspaceAPISetTabLabel extends LightningElement {
    @wire(IsConsoleNavigation) isConsoleNavigation;

    async setTabLabel() {
        if (!this.isConsoleNavigation) {
            return;
        }

        // Change current tab label
        const { tabId } = await getFocusedTabInfo();
        await setTabLabel(tabId, 'Awesome Label');
    }
}

Setting Tab Icon

Update the icon displayed on a tab. workspaceAPISetTabIcon.js:

import { LightningElement, wire } from 'lwc';
import {
    IsConsoleNavigation,
    getFocusedTabInfo,
    setTabIcon
} from 'lightning/platformWorkspaceApi';

export default class WorkspaceAPISetTabIcon extends LightningElement {
    @wire(IsConsoleNavigation) isConsoleNavigation;

    async setTabIcon() {
        if (!this.isConsoleNavigation) {
            return;
        }

        // Change current tab icon
        const { tabId } = await getFocusedTabInfo();
        await setTabIcon(tabId, 'utility:animal_and_nature', {
            iconAlt: 'Animal and Nature'
        });
    }
}

Focusing Tabs

Bring a specific tab into focus. workspaceAPIFocusTab.js:

import { LightningElement, wire } from 'lwc';
import {
    focusTab,
    IsConsoleNavigation,
    getFocusedTabInfo,
    getAllTabInfo
} from 'lightning/platformWorkspaceApi';

export default class WorkspaceAPIFocusTab extends LightningElement {
    @wire(IsConsoleNavigation) isConsoleNavigation;

    async focusNextTab() {
        if (!this.isConsoleNavigation) {
            return;
        }

        // Get current tab and figure out which tab is next
        const { tabId } = await getFocusedTabInfo();
        const allTabs = await getAllTabInfo();
        const selectedTabIndex = allTabs.findIndex(
            (possibleNextTab) => possibleNextTab.tabId === tabId
        );
        const nextTabId = allTabs[selectedTabIndex + 1].tabId;

        // Focus on next tab
        await focusTab(nextTabId);
    }
}

Refreshing Tabs

Refresh the content of a tab and optionally its subtabs. workspaceAPIRefreshTab.js:

import { LightningElement, wire } from 'lwc';
import {
    IsConsoleNavigation,
    getFocusedTabInfo,
    refreshTab
} from 'lightning/platformWorkspaceApi';

export default class WorkspaceAPIRefreshTab extends LightningElement {
    @wire(IsConsoleNavigation) isConsoleNavigation;

    async refreshTab() {
        if (!this.isConsoleNavigation) {
            return;
        }

        // Refresh current tab and all subtabs
        const { tabId } = await getFocusedTabInfo();
        await refreshTab(tabId, {
            includeAllSubtabs: true
        });
    }
}

Closing Tabs

Close tabs programmatically. workspaceAPICloseTab.js:

import { LightningElement, wire } from 'lwc';
import {
    closeTab,
    IsConsoleNavigation,
    getFocusedTabInfo
} from 'lightning/platformWorkspaceApi';

export default class WorkspaceAPICloseTab extends LightningElement {
    @wire(IsConsoleNavigation) isConsoleNavigation;

    async closeTab() {
        if (!this.isConsoleNavigation) {
            return;
        }

        // Close current tab
        const { tabId } = await getFocusedTabInfo();
        await closeTab(tabId);
    }
}

Preventing Tab Close

Disable the close button on a tab. workspaceAPIDisableTabClose.js:

import { LightningElement, wire } from 'lwc';
import {
    IsConsoleNavigation,
    getFocusedTabInfo,
    disableTabClose
} from 'lightning/platformWorkspaceApi';

export default class WorkspaceAPIDisableTabClose extends LightningElement {
    @wire(IsConsoleNavigation) isConsoleNavigation;

    async disableTabClose() {
        if (!this.isConsoleNavigation) {
            return;
        }

        // Disable close for current tab
        const { tabId } = await getFocusedTabInfo();
        await disableTabClose(tabId, true);
    }
}

Getting Tab Information

Get Focused Tab Info

import { getFocusedTabInfo } from 'lightning/platformWorkspaceApi';

const tabInfo = await getFocusedTabInfo();
console.log('Current tab ID:', tabInfo.tabId);
console.log('Is subtab:', tabInfo.isSubtab);
console.log('Page reference:', tabInfo.pageReference);

Get All Tab Info

import { getAllTabInfo } from 'lightning/platformWorkspaceApi';

const allTabs = await getAllTabInfo();
allTabs.forEach(tab => {
    console.log('Tab ID:', tab.tabId);
    console.log('Tab label:', tab.title);
    console.log('Is focused:', tab.focused);
});

Get All Subtab Info

import { getAllTabInfo } from 'lightning/platformWorkspaceApi';

const { tabId } = await getFocusedTabInfo();
const subtabs = await getAllTabInfo({ tabId });

Highlighting Tabs

Highlight a tab to draw attention to it.

import { setTabHighlighted } from 'lightning/platformWorkspaceApi';

// Highlight tab
await setTabHighlighted(tabId, true, {
    pulse: true,
    state: 'success'
});

Available states:

success - Green highlight
warning - Orange highlight
error - Red highlight
info - Blue highlight (default)

Common Patterns

async openRelatedRecord(recordId) {
    if (!this.isConsoleNavigation) {
        return;
    }
    
    const { tabId } = await getFocusedTabInfo();
    await openSubtab(tabId, {
        pageReference: {
            type: 'standard__recordPage',
            attributes: {
                recordId: recordId,
                actionName: 'view'
            }
        },
        focus: true
    });
}

Update Tab Label with Record Name

import { getRecord } from 'lightning/uiRecordApi';
import NAME_FIELD from '@salesforce/schema/Account.Name';

@wire(getRecord, { recordId: '$recordId', fields: [NAME_FIELD] })
wiredRecord({ data }) {
    if (data && this.isConsoleNavigation) {
        const name = data.fields.Name.value;
        getFocusedTabInfo().then(({ tabId }) => {
            setTabLabel(tabId, name);
        });
    }
}

Close All Subtabs

async closeAllSubtabs() {
    if (!this.isConsoleNavigation) {
        return;
    }
    
    const { tabId } = await getFocusedTabInfo();
    const subtabs = await getAllTabInfo({ tabId });
    
    for (const subtab of subtabs) {
        await closeTab(subtab.tabId);
    }
}

Best Practices

Always Check Console Context

Never call Workspace API methods without checking IsConsoleNavigation first:

@wire(IsConsoleNavigation) isConsoleNavigation;

async myMethod() {
    if (!this.isConsoleNavigation) {
        return;
    }
    // Workspace API calls
}

Handle Async Operations

Workspace API methods return promises. Use async/await or .then():

// Good - async/await
async openNewTab() {
    const result = await openTab({ /* config */ });
    console.log('Tab opened:', result.tabId);
}

// Good - promise chain
openNewTab() {
    openTab({ /* config */ })
        .then(result => {
            console.log('Tab opened:', result.tabId);
        });
}

Cache Tab IDs When Needed

If you need to reference a tab multiple times, cache the ID:

connectedCallback() {
    if (this.isConsoleNavigation) {
        getFocusedTabInfo().then(({ tabId }) => {
            this.currentTabId = tabId;
        });
    }
}

Provide User Feedback

Let users know when tab operations complete:

import { ShowToastEvent } from 'lightning/platformShowToastEvent';

async openNewTab() {
    try {
        await openTab({ /* config */ });
        this.dispatchEvent(
            new ShowToastEvent({
                title: 'Success',
                message: 'Tab opened',
                variant: 'success'
            })
        );
    } catch (error) {
        this.dispatchEvent(
            new ShowToastEvent({
                title: 'Error',
                message: error.message,
                variant: 'error'
            })
        );
    }
}

Get Started

Basics

Component Composition

Event Handling

Data Access

Component Features

Navigation

Styling

Advanced Topics

Guides

Checking Console Context

Opening Tabs

Opening Different Page Types

Opening Subtabs

Setting Tab Label

Setting Tab Icon

Focusing Tabs

Refreshing Tabs

Closing Tabs

Preventing Tab Close

Getting Tab Information

Get Focused Tab Info

Get All Tab Info

Get All Subtab Info

Highlighting Tabs

Common Patterns

Update Tab Label with Record Name

Close All Subtabs

Best Practices

Always Check Console Context

Handle Async Operations

Cache Tab IDs When Needed

Provide User Feedback

​Checking Console Context

​Opening Tabs

​Opening Different Page Types

​Opening Subtabs

​Setting Tab Label

​Setting Tab Icon

​Focusing Tabs

​Refreshing Tabs

​Closing Tabs

​Preventing Tab Close

​Getting Tab Information

​Get Focused Tab Info

​Get All Tab Info

​Get All Subtab Info

​Highlighting Tabs

​Common Patterns

​Open Related Record in Subtab

​Update Tab Label with Record Name

​Close All Subtabs

​Best Practices

​Always Check Console Context

​Handle Async Operations

​Cache Tab IDs When Needed

​Provide User Feedback

​Related Resources

Checking Console Context

Opening Tabs

Opening Different Page Types

Opening Subtabs

Setting Tab Label

Setting Tab Icon

Focusing Tabs

Refreshing Tabs

Closing Tabs

Preventing Tab Close

Getting Tab Information

Get Focused Tab Info

Get All Tab Info

Get All Subtab Info

Highlighting Tabs

Common Patterns

Open Related Record in Subtab

Update Tab Label with Record Name

Close All Subtabs

Best Practices

Always Check Console Context

Handle Async Operations

Cache Tab IDs When Needed

Provide User Feedback

Related Resources