openSubtab() for Lightning Experience

Opens a subtab within a workspace tab. If the subtab is already open, the subtab is focused. This method works only in Lightning console apps.

Arguments

The method provides the same argument for both Aura Components and Lightning Web Components (LWC). However, icon, iconAlt, and label are supported only for LWC.

Name	Type	Description
`parentTabId`	string	The ID of the workspace tab within which the new subtab opens. You must pass the parent tab ID into the `openSubtab()` method.
`pageReference`	object	Optional. Specifies the `pageReference` to open.
`recordId`	ID	Optional. Specifies the record to open.
`url`	string	Optional. The URL representing the content of the new workspace tab. The URL can be either relative or absolute. To use a third-party domain, add the site as a CSP Trusted Site.
`focus`	boolean	Optional. Specifies whether the new subtab has focus. To display the subtab immediately, set `focus` to `true`. To open the subtab in the background, set `focus` to `false`.
`icon`	string	Optional. An SLDS icon key. See a full list of icon keys on the SLDS reference site. Available for LWC only.
`iconAlt`	string	Optional. Alternative text for the icon. Available for LWC only.
`label`	string	Optional. The text label for the icon. Available for LWC only.

pageReference, recordId, and url are prioritized in that order. Providing arguments with a higher priority means the others get ignored.

Note

LWC Sample Code

This component retrieves the enclosing tab ID using the EnclosingTabId wire adapter. It opens a subtab on the current tab when the handleClick() function is called. If the component doesn’t reside inside a tab or subtab, tabId is null.

To check if the current tab is a subtab, use getTabInfo(). If the current tab is a subtab, pass in the parent tab ID to the openSubtab() function.

1import { LightningElement, wire } from 'lwc';
2import { EnclosingTabId, getTabInfo, openSubtab } from 'lightning/platformWorkspaceApi';
3
4export default class OpenSubtabExample extends LightningElement {
5  @wire(EnclosingTabId) tabId;
6
7  async handleClick() {
8    if (!this.tabId) {
9      return;
10    }
11
12    const tabInfo = await getTabInfo(this.tabId);
13    const primaryTabId = tabInfo.isSubtab ? tabInfo.parentTabId : tabInfo.tabId;
14
15    // Open a record as a subtab of the current tab
16    await openSubtab(primaryTabId, { recordId: 'YOUR_RECORD_ID', focus: true });
17  }
18}

Where YOUR_RECORD_ID is a variable.

For another example that uses openSubtab(), see the workspaceAPIOpenSubtab component in 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, opens a subtab within a workspace tab.

Component code:

1<aura:component implements="flexipage:availableForAllPageTypes" access="global" >
2    <lightning:workspaceAPI aura:id="workspace" />
3    <lightning:button label="Open Tab with Subtab" onclick="{! c.openTabWithSubtab }" />
4 </aura:component>

Controller code:

1({
2    openTabWithSubtab : function(component, event, helper) {
3        var workspaceAPI = component.find("workspace");
4        workspaceAPI.openTab({
5            url: '/lightning/r/Account/001xx000003DI05AAG/view',
6            focus: true
7        }).then(function(response) {
8            workspaceAPI.openSubtab({
9                parentTabId: response,
10                url: '/lightning/r/Contact/003xx000004Ts30AAC/view',
11                focus: true
12            });
13        })
14        .catch(function(error) {
15            console.log(error);
16        });
17    }
18})

The relative URL used in this example is a placeholder. To try this example yourself, use a relative URL with a record ID from your org.

Note

Response

This method returns a promise that, upon success, resolves to the ID of the new subtab.