Tabs

Summary

Tabs are used for alternating between views within the same context, not to navigate to different areas. For navigation refer to the horizontal navigation guidelines.

Status

API status:	general
Included in AUI core?	Yes. You do not need to explicitly require the web resource key.
Web resource key:	`com.atlassian.auiplugin:ajs`
Experimental since:	3.0

Examples

Designers

#	First name	Last name	Username
1	Matt	Bond	mbond
2	Ross	Chaldecott	rchaldecott
3	Henry	Tapia	htapia

Developers

#	First name	Last name	Username
4	Seb	Ruiz	sruiz
7	Sean	Curtis	scurtis
8	Matthew	Watson	mwatson

Product management

#	First name	Last name	Username
5	Jens	Schumacher	jschumacher
6	Sten	Pittet	spittet
9	James	Dumay	jdumay

Code

HTML

AUI Tabs core API is HTML and has three key parts:

.aui-tabs: The root element of the AUI Tabs
Tab pairs - each tab must have a control in the menu and a corresponding tab pane:
- .tabs-menu: The menu of controls to change which tab pane is active
- .tabs-pane: Each pane contains the content of one tab

Notes:

Remember all IDs must be unique in each given page/location.
Each menu item is an li element with an A element inside. The A element must contain an href to the approriate tab-pane id.
One instance of li.menu-item must have the class active-tab
One instance of .tab-pane must have the class active-pane

<div class="aui-tabs horizontal-tabs">
    <ul class="tabs-menu">
        <li class="menu-item active-tab">
            <a href="#tabs-example-first"><strong>Tab 1</strong></a>
        </li>
        <li class="menu-item">
            <a href="#tabs-example-second"><strong>Tab 2</strong></a>
        </li>
    </ul>
    <div class="tabs-pane active-pane" id="tabs-example-first">
        <h2>This is Tab 1</h2>
        <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>
    </div>
    <div class="tabs-pane" id="tabs-example-second">
        <h2>This is Tab 2</h2>
        <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>
    </div>
</div><!-- // .aui-tabs -->

Options

Class	Applies to element	Effect
`horizontal-tabs`	.aui-tabs	Sets the tab set to display as horizontal tabs (triggers across the top)
`vertical-tabs`	.aui-tabs	Sets the tab set to display as vertical tabs (triggers on the left)
`aui-tabs-disabled`	.aui-tabs	Disables the tab set, so the triggers behave as links. Sometimes referred to as "page tabs" as the design looks like tabs, but each "tab" behaves like a standard HTML page (loads via a separate URL). Note this will stop the tab links having tab events bound during load. Applying the class after the page has loaded has no effect.
`active-tab`	one instance of .menu-item per tab set	Sets the active tab trigger on initial page load.
`active-pane`	one instance of .tabs-pane per tab set	Sets the active tab pane on initial page load.

HTML Attributes Applies to element Effect Example

HTML Attributes	Applies to element	Effect	Example
`data-aui-persistent`	.aui-tabs	Sets whether tab state is persistent. If this attribute is defined, tab selection is persisted in the user's browser using HTML5 local storage. If this attribute is defined, the tab group must have an id attribute defined. This value for this attribute can be one of: `true` or empty - for the default case `false` - selection is not persisted any other value - the attribute value is appended to the local storage key. This is typically used to separate local storage per-user in the same browser - eg `data-aui-persistent="{{username}}"`	`// example of enabling persistent tabs. No value is given so default key is used. <div id="tab-group-one" class="aui-tabs horizontal-tabs" data-aui-persistent>` `// example of enabling persistent tabs with unique value. Here the unique value is the users name. <div id="tab-group-one" class="aui-tabs horizontal-tabs" data-aui-persistent="username">`
`data-aui-responsive`	.aui-tabs.horizontal-tabs	Makes the set of tabs responsive to the size of the container. This means that instead of wrapping the overflowing tabs will be placed into a dropdown. The presence of the attribute is enough to enable the option however you can also explicitly pass in `true`.	`<div class="aui-tabs horizontal-tabs" id="responsive-tabs" data-aui-responsive>`

data-aui-persistent

.aui-tabs

Sets whether tab state is persistent. If this attribute is defined, tab selection is persisted in the user's browser using HTML5 local storage. If this attribute is defined, the tab group must have an id attribute defined. This value for this attribute can be one of:

true or empty - for the default case
false - selection is not persisted
any other value - the attribute value is appended to the local storage key. This is typically used to separate local storage per-user in the same browser - eg data-aui-persistent="{{username}}"

// example of enabling persistent tabs. No value is given so default key is used.
<div id="tab-group-one" class="aui-tabs horizontal-tabs" data-aui-persistent>

// example of enabling persistent tabs with unique value. Here the unique value is the users name.
<div id="tab-group-one" class="aui-tabs horizontal-tabs" data-aui-persistent="username">

data-aui-responsive

.aui-tabs.horizontal-tabs

Makes the set of tabs responsive to the size of the container. This means that instead of wrapping the overflowing tabs will be placed into a dropdown.

The presence of the attribute is enough to enable the option however you can also explicitly pass in true.

<div class="aui-tabs horizontal-tabs" id="responsive-tabs" data-aui-responsive>

JavaScript Functions

AUI Tabs can be implemented entirely using HTML markup however there are some javascript functions available.

Function Effect Example

Function	Effect	Example
`AJS.tabs.change(tab, e);`	Programmatically changes the active tab. `tab` - This must be a jQuery object of the anchor for the tab you wish to change to. `e` - Optional. You can also pass in an event if you choose to call this from an event handler.	`// example of changing a tab via JS AJS.tabs.change(AJS.$("a[href=#horizontal-second]"));`
`AJS.tabs.setup()`	This function is run when AJS.tabs is first loaded; it sets up events etc. You will need to run this again if you add new tab sets after page load.	`// example of changing a tab via JS AJS.tabs.setup();`

AJS.tabs.change(tab, e);

Programmatically changes the active tab.

tab - This must be a jQuery object of the anchor for the tab you wish to change to.
e - Optional. You can also pass in an event if you choose to call this from an event handler.

// example of changing a tab via JS
AJS.tabs.change(AJS.$("a[href=#horizontal-second]"));

AJS.tabs.setup()

This function is run when AJS.tabs is first loaded; it sets up events etc. You will need to run this again if you add new tab sets after page load.

// example of changing a tab via JS
AJS.tabs.setup();

JavaScript Events

AJS.tabs only emits one event: tabSelect. When a tab is selected, it fires tabSelect which includes a reference to an object containing both the pane and the tab selected.