lightning:tabset (Beta)

Represents a list of tabs.

A lightning:tabset displays a tabbed container with multiple content areas, only one of which is visible at a time. Tabs are displayed horizontally inline with content shown below it. A tabset can hold multiple lightning:tab components as part of its body. The first tab is activated by default, but you can change the default tab by setting the selectedTabId attribute on the target tab.

Use the variant attribute to change the appearance of a tabset. The variant attribute can be set to default, scoped, or vertical. The default variant underlines the active tab. The scoped tabset styling displays a closed container with a defined border around the active tab. The vertical tabset displays a scoped tabset with the tabs displayed vertically instead of horizontally.

This component inherits styling from tabs in the Lightning Design System.

Here is an example.

<aura:component>
    <lightning:tabset>
        <lightning:tab label="Item One">
            Sample Content One
        </lightning:tab>
        <lightning:tab label="Item Two">
            Sample Content Two
        </lightning:tab>
    </lightning:tabset>
</aura:component>
        

You can lazy load content in a tab by using the onactive attribute to inject the tab body programmatically. Here's an example with two tabs, which loads content when they're active.

<lightning:tabset variant="scoped">
    <lightning:tab onactive="{! c.handleActive }" label="Accounts" id="accounts" />
    <lightning:tab onactive="{! c.handleActive }" label="Cases" id="cases" />
</lightning:tabset>

In your client-side controller, pass in the component and event to the helper.

({
    handleActive: function (cmp, event, helper) {
        helper.lazyLoadTabs(cmp, event);
    }
})

Your client-side helper identifies the tab that's selected and adds your content using $A.createComponent().

({
    lazyLoadTabs: function (cmp, event) {
        var tab = event.getSource();
        switch (tab.get('v.id')) {
            case 'accounts' :
                this.injectComponent('c:myAccountComponent', tab);
                break;
            case 'cases' :
                this.injectComponent('c:myCaseComponent', tab);
                break;
        }
    },
    injectComponent: function (name, target) {
        $A.createComponent(name, {
        }, function (contentComponent, status, error) {
            if (status === "SUCCESS") {
                target.set('v.body', contentComponent);
            } else {
                throw new Error(error);
            }
        });
    }
})

Dynamically Creating Tabs

To create tabs dynamically, use $A.createComponent(). This example creates a new tab when a button is clicked, and uses the moretabs facet to hold your new tab.

<aura:component>
    <aura:attribute name="moretabs" type="Aura.Component[]"/>
        <lightning:tabset variant="scoped">
            <lightning:tab label="Item One">
                 Some content here
            </lightning:tab>
            {!v.moretabs}
        </lightning:tabset>
        <!-- Click button to create a new tab -->
        <lightning:button label="Add tab" onclick="{!c.addTab}"/>
        

The client-side controller adds the onactive event handler and creates the tab content when the new tab is clicked.

({
    addTab: function(component, event) {
        $A.createComponent("lightning:tab", {
            "label": "New Tab",
            "id": "new",
            "onactive": component.getReference("c.addContent")
        }, function (newTab, status, error) {
            if (status === "SUCCESS") {
                var body = component.get("v.moretabs");
                component.set("v.moretabs", newTab);
            } else {
                throw new Error(error);
            }
        });
    },
    addContent : function(component, event) {
        var tab = event.getSource();
        switch (tab.get('v.id')){
            case 'new':
                // Display a badge in the tab content.
                // You can replace lightning:badge with a custom component.
                $A.createComponent("lightning:badge", {
                    "label": "NEW"
                }, function (newContent, status, error) {
                    if (status === "SUCCESS") {
                        tab.set('v.body', newContent);
                    } else {
                        throw new Error(error);
                    }
                });
                break;
        }
    }
})

Alternatively, you can conditionally display a tab using aura:if. This example creates the tab on initialization but hides it until the desired condition is met. You can display the hidden tab using cmp.set('v.displayTab', !cmp.get('v.displayTab'));.

<aura:component>
    <aura:attribute name="displayTab" type="Boolean" default="false" />
    <lightning:tabset>
        <aura:if isTrue="{! v.displayTab }">
            <lightning:tab label="My Hidden Tab">
                Your content here
            </lightning:tab>
        </aura:if>
        <!-- Your other lightning:tab components here -->
    </lightning:tabset>
</aura:component>
Selecting a Tab Programmatically

To select a tab programmatically, add a change handler for the id attribute on lightning:tab. In this example, tabId is monitored by the change handler, which then fires the handleChange controller action to update the selectedTabId attribute.

<aura:component>
    <aura:attribute name="tabId" type="String" default="2"/>
    <aura:handler name="change" value="{!v.tabId}" action="{!c.handleChange}"/>     
    <lightning:tabset aura:id="tabs" selectedTabId="{!v.tabId}">
        <lightning:tab label="Item One" id="1">
            Your content here
        </lightning:tab>
        <lightning:tab label="Item Two" id="2">
            Your content here
        </lightning:tab>
        <lightning:tab label="Item Three" id="3">
            Your content here
        </lightning:tab>
    </lightning:tabset>
    <lightning:button label="Toggle Tab" onclick="{!c.handleClick}" />
</aura:component>

After updating the tab ID to the new value, display the corresponding tab by updating the value on selectedTabId.

({
    handleClick: function(cmp) {
        cmp.set("v.tabId", "3");
    },
    handleChange: function(cmp) {
        //Display content on the Item Three tab
        var selected = cmp.get("v.tabId");
        cmp.find("tabs").set("v.selectedTabId", selected);
    }
})

Usage Considerations

When you load more tabs than can fit the width of the view port, the tabset provides navigation buttons for the overflow tabs.

This component creates its body during runtime. You won’t be able to reference the component during initialization. You can set your content using value binding with component attributes instead.

For example, you can't create a lightning:select component in a tabset by loading the list of options dynamically during initialization using the init handler. However, you can create the list of options by binding the component attribute to the values. By default, the option's value attribute is given the same value as the option passed to it unless you explicitly assign a value to it.

<aura:component>
    <aura:attribute name="opts" type="List" default="['red', 'blue', 'green']" />
    <lightning:tabset>
        <lightning:tab label="View Options">
           <lightning:select name="colors" label="Select a color:">
                    <aura:iteration items="{!v.opts}" var="option">
                        <option>{! option }</option>
                    </iteration>
            </lightning:select>
        </lightning:tab>
    </lightning:tabset>
</aura:component>

Attributes

Attribute Name Attribute Type Description Required?
body ComponentDefRef[] The body of the component. This could be one or more lightning:tab components.
class String A CSS class for the outer element, in addition to the component's base classes.
title String Displays tooltip text when the mouse moves over the element.
variant String The variant changes the appearance of the tabset. Accepted variants are default, scoped, and vertical.
selectedTabId String Allows you to set a specific tab to open by default. If this attribute is not used, the first tab opens by default.
onselect Action The action that will run when the tab is clicked.