Tabs

Ask a question Design guidelines

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
Web resource key: com.atlassian.auiplugin:aui-tabs
AMD Module key: N/A
Experimental API: 3
General API: 3.1

Examples

Designers

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

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 appropriate 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

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
data-aui-persist .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 and each tab must have an id attribute defined. The value for the data-aui-persist 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-persist="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.

JavaScript functions

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

Function Effect Example
AJS.tabs.change(tab, e);

Programmatically changes the active tab.

  • tab - This must be a an object representing the anchor for the tab you wish to change to. You can pass here a jQuery collection (only the first element from the collection will be used) or an instance of HTMLElement or a query string (first found HTMLElement will be used).
  • e - Optional. You can also pass in an event if you choose to call this from an event handler.
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.

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.