Workspace API

lightning:workspaceAPI

Work with workspace tabs and subtabs in a Lightning console app.

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

For Use In

Lightning Experience

This component allows you to access methods for programmatically controlling workspace tabs and subtabs in a Lightning console app. In Lightning console apps, records open as workspace tabs and their related records open as subtabs.

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

This example opens a new tab displaying the record with the given relative URL in the url attribute 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. For more information on these methods, see the Console Developer Guide.

closeTab({tabId})

  • tabId (string): ID of the workspace tab or subtab to close.

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

focusTab({tabId})

  • tabId (string): The ID of the workspace tab or subtab on which to focus.

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

getAllTabInfo()

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

getFocusedTabInfo()

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

getTabInfo({tabId})

  • tabId (string): ID of the tab for which to retrieve the information.

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

getTabURL({tabId})

  • tabId (string): ID of the tab for which to retrieve the URL.

Returns a Promise. Success resolves to the tab URL. The Promise will be rejected on error.

isSubtab({tabId})

  • tabId (string): ID of the tab.

Returns a Promise. Success resolves to true if the tab is a subtab, false otherwise. The Promise will be rejected on error.

isConsoleNavigation()

Returns a Promise. Success resolves to true if console navigation is present, false otherwise. The Promise will be rejected on error.

getEnclosingTabId()

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

openSubtab({parentTabId, pageReference, recordId, url, focus})

  • parentTabId (string): ID of the workspace tab within which the new subtab should open.
  • pageReference (object): Optional. A PageReference representing the content of the new subtab.
  • recordId (string): Optional. A record ID representing the content of the new subtab.
  • url (string): Optional. The URL representing the content of the new subtab. URLs can be either relative or absolute.
  • focus (boolean): Optional. Specifies whether the new subtab has focus.

Returns a Promise. Success resolves to the tabId of the subtab. The Promise will be rejected on error.

openTab({pageReference, recordId, url, focus, overrideNavRules})

  • pageReference (object): Optional. A PageReference representing the content of the new tab.
  • recordId (string): Optional. A record ID representing the content of the new tab.
  • url (string): Optional. The URL representing the content of the new tab. URLs can be either relative or absolute.
  • focus (boolean): Optional. Specifies whether the new tab has focus.
  • overrideNavRules (boolean): Optional. Specifies whether to override nav rules when opening the new tab.

Returns a Promise. Success resolves to the tabId of the workspace. The Promise will be rejected on error.

setTabIcon({tabId, icon, iconAlt})

  • tabId (string): The ID of the tab for which to set the icon.
  • icon (string): An SLDS icon key. See a full list of icon keys on the SLDS reference site.
  • iconAlt (string): Optional. Alternative text for the icon.

Returns a Promise. Success resolves to a tabInfo object of the modified tab. The Promise will be rejected on error.

setTabLabel({tabId, label})

  • tabId (string): The ID of the tab for which to set the label.
  • label (string): The label of the workspace tab or subtab.

Returns a Promise. Success resolves to a tabInfo object of the modified tab. The Promise will be rejected on error.

setTabHighlighted({tabId, highlighted, options})

  • tabId (string): The ID of the tab for which to highlight.
  • highlighted (boolean): Specifies whether the new tab should be highlighted.
  • options (object): Optional. Additional options that modify the appearance of the highlighted tab.

Returns a Promise. Success resolves to a tabInfo object of the modified tab. The Promise will be rejected on error.

disableTabClose({tabId, disabled})

  • tabId (string): The ID of the tab for which to disable or enable close capabilities.
  • disabled (boolean): Specifies whether the tab should have close capabilities disabled or enabled.

Returns a Promise. Success resolves to a tabInfo object of the modified tab. The Promise will be rejected on error.

refreshTab({tabId, includeAllSubtabs})

  • tabId (string): ID of the workspace tab or subtab to refresh.
  • includeAllSubtabs (boolean): Optional. If the tabId corresponds to a workspace tab, all subtabs within that workspace are refreshed. The default is true. Keep in mind that the first subtab has the same tabId as the workspace tab.

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

generateConsoleURL({pageReferences})

  • pageReferences (array): An array of PageReferences to a workspace or workspace and subtabs to generate a URL for.

Generates a URL to a workspace or workspace and subtabs. Returns a Promise. Success resolves to the active tab id. The Promise will be rejected on error.

openConsoleURL({url, focus, labels})

  • url (string): The URL representing the content of the new workspace or workspace and subtabs.
  • focus (boolean): Optional. Specifies whether the new active tab has focus.
  • labels (array): Optional. An array of labels to be applied to the workspace or workspace and subtabs.

Opens a URL generated via the generateConsoleURL API. Returns a Promise. Success resolves to true. The Promise will be rejected on error.

addToBrowserTitleQueue({title})

  • title (string): Title that needs to be added to the browser title queue

Adds a browser tab title to a list of titles, which rotates every few seconds. Returns a Promise. Success resolves to true. The Promise will be rejected on error.

removeFromBrowserTitleQueue({title})

  • title (string): Title that needs to be removed from the browser title queue

Removes a browser tab title from the list of titles, which rotates every few seconds. Returns a Promise. Success resolves to true if title was removed, false otherwise. The Promise will be rejected on error.