openTab() for Lightning Experience

Opens a new workspace tab. If the tab is already open, the tab is focused.

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
pageReference	object	Optional. Generates a unique URL to open. A page reference contains attributes that apply to all pages of that type. See the Aura pageReference types and LWC pageReference types.
recordId	ID	Optional. Specifies the record to open.
url	URL	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 tab has focus. To display the tab immediately, set focus to `true`. To open the tab in the background, set focus to `false`.
overrideNavRules	boolean	Optional. Specifies whether the open tab respects existing navigation rules. This argument has no effect on records that have no navigation rules configured and URLs that do not point to a record.
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 an argument with a higher priority means the others are ignored.

Note

LWC Sample Code

This component has a function that opens a specified tab and applies focus on it.

1import { LightningElement } from 'lwc';
2import { openTab, focusTab } from 'lightning/platformWorkspaceApi';
3
4export default class MyComponent extends LightningElement {
5
6   focusNewTab(event) {
7       openTab({
8            url: '/lightning/r/Account/001R0000003HgssIAC/view',
9            label: 'Global Media',
10            focus: true
11       }).catch((error) => {
12            console.log(error);
13       });
14   }
15}

Example

The lwc-recipes repo has a workspaceAPIOpenTab component that demonstrates usage of the openTab() method.

Aura Components Sample Code

This component has a button that when pressed, opens a tab.

Component code:

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

Pass in a pageReference Controller code (pageReference) using the standard__recordPage type:

1({
2openTab: function(component, event, helper) {
3        var workspaceAPI = component.find("workspace");
4        workspaceAPI.openTab({
5            pageReference: {
6                "type": "standard__recordPage",
7                "attributes": {
8                    "recordId":"500xx000000Ykt2AAC",
9                    "actionName":"view"
10                },
11                "state": {}
12            },
13            focus: true
14        }).then(function(response) {
15            workspaceAPI.getTabInfo({
16                tabId: response
17        }).then(function(tabInfo) {
18            console.log("The recordId for this tab is: " + tabInfo.recordId);
19        });
20        }).catch(function(error) {
21            console.log(error);
22        });
23    }
24)}

Controller code (recordId):

1({
2    openTab : function(component, event, helper) {
3        var workspaceAPI = component.find("workspace");
4        workspaceAPI.openTab({
5            recordId: '001xx000003DIkeAAG',
6            focus: true
7        }).then(function(response) {
8            workspaceAPI.getTabInfo({
9                  tabId: response
10            }).then(function(tabInfo) {
11            console.log("The url for this tab is: " + tabInfo.url);
12            });
13        })
14        .catch(function(error) {
15               console.log(error);
16        });
17    }
18})

Controller code (url):

1({
2    openTab : 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.getTabInfo({
9                tabId: response
10            }).then(function(tabInfo) {
11            console.log("The recordId for this tab is: " + tabInfo.recordId);
12            });
13        }).catch(function(error) {
14                console.log(error);
15        });
16    }
17})

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.