A tab is a hidden section of content activated by a menu




A basic tab

A tab is hidden by default, and will only become visible when given the class name active or when activated with Javascript. For more information, see the usage section.



A tab can be activated, and visible on the page


A tab can display a loading indicator

Basic Examples

Basic Tabs

Tabs are connecting using paths specified in the data-tab attribute. Tab is then initialized in Javascript on the activating elements.

To have a tab visible on page load, add the class active to both the initializing menu and the tab.
$('.menu .item') .tab() ;

Multiple Tab Groups

There are a several of ways to include independent tab groups on the same page, even with history. One of the easiest ways is provide a specific parent context for each tab group.

If you are using tab contexts inside of tabs, you can also specify childrenOnly: true which will only look for tabs as the immediate children of the given context, or context: 'parent' a special keyword which avoids having to create unique selectors for each group.
$('#context1 .menu .item') .tab({ context: $('#context1') }) ; $('#context2 .menu .item') .tab({ // special keyword works same as above context: 'parent' }) ;

Default Paths

When you specify a path like first/ after opening the tab it will look for the any child paths and open the first. In this example even if the path is first/, the tab corresponding with first/a will automatically also be open because it is the default child tab. This will work recursively for as many additional child tab groups as you include.

Each of these examples is initialized with a context to prevent contamination with other tab examples on this page. This is not necessary unless using multiple tab systems on a single page.
$('.paths.example .menu .item') .tab({ context: '.paths.example' }) ;

Remote Examples

Retreiving Remote Content

Using auto: true will load the tab's path from your server with additional headers to specify an in-page request. When cache: true is set, re-opening a tab will be loaded from cache without a server request.

API requests for the following example have been faked using mockResponse API setting to avoid network overhead.
$('.dynamic.example .menu .item') .tab({ cache: false, // faking API request apiSettings: { loadingDuration : 300, mockResponse : function(settings) { var response = { first : 'AJAX Tab One', second : 'AJAX Tab Two', third : 'AJAX Tab Three' }; return response[]; } }, context : 'parent', auto : true, path : '/' }) ;

AJAX Tab One

Evaluating Scripts in HTML

By default, script tags included in HTML will only be evaluated on first load. To change this behavior you can adjust the evaluateScripts setting.

$('.eval.example .menu .item') .tab({ evaluateScripts : 'once', context : 'parent', auto : true, path : '/' }) ;

AJAX Tab One

History Examples

Using Hash History

For static sites, or sites that only require simple history, in-page links can be used to trigger different local tab states

$('.history.example .menu .item') .tab({ context : '.history.example', history : true }) ;

Using HTML5 State

For sites that are able to replicate change on the server, tab can automatically map changes in tab navigation to html5 state.

Since these docs are statically hosted on GitHub Pages, html5 state tabs are not demonstrable from the docs. You will need to try this example in your own code.
$(' .item') .tab({ history : true, historyType : 'state', // base url for all other path changes path : '/my/base/url' }) ;

Initializing Tabs

...with Menus

Tabs are usually used in concert with an element that activates the tab. Tabs are initialized on the activating item instead of the tab.

Tabs are connected to their activators with a metadata attribute data-tab. This should be added to both the activating element and the tab itself.

$(' .item').tab();

...without Menus

If there are no menus that activate tab elements on the page, tabs can be initialized globally by using $.tab() and activated programmatically using $.tab('change tab', path);

$('.ui.button') .on('click', function() { // programmatically activating tab $.tab('change tab', 'tab-name'); }) ;
Activate Tab

Default Tabs

After any tab is opened it will look for a default tab to open inside of the current tab. This is the first tab that begins with the same stem url as the parent tab. For example a tab with the path data-tab="home" might open a tab automatically data-tab="/home/inbox".

This will happen recursively for every tab open, allowing as many levels of tabs as you like.

Managing State

...with Hash Tags

Hash tags use in page links and onhashstatechange to create history events for each tab. This is sometimes easier to use than the more advanced push state, because it does not require you to route those URLs on your server. All in page links will route to the same url.

Tabs use Asual's Address library to provide cross-browser push state support. This is a required dependency for tabs with history to work correctly.

$(' .item') .tab({ history: true, historyType: 'hash' }) ;

...with HTML5 State

Tabs can can use html5 push state to manage page state without using #/foo links. When a user refreshes a page using push state the server will be queried for the new url. This means you must set up appropriate routes in your backend to match each link.

$(' .item') .tab({ history: true, historyType: 'state', path: '/modules/tab.html' }) ;

Setting Paths

Using historyType: state requires specifying a base URL without any internal state. This cannot be set automatically to window.location because all tabs with html5 state will appear as normal page urls, and route accordingly.

HTML5 state will only work with dynamic site back-ends because it requires each tab path to correctly route on the server to the appropriate content.

$(' .item') .tab({ history: true, historyType: 'state' path: '/modules/tab.html' }) ;
Using an incorrect base path is a common error when using HTML5 state, and can cause unusual behaviors.

AJAX Content

...with automatic routing

Specifying the setting auto: true, will automatically retrieve content at a remote url matching the url set in the browser.

So for example the tab inbox will retrieve content from the URL base-url/inbox/

The URL will receive an addition HTTP Header 'X-Remote': true. You can use this on your server's back-end to determine whether a request is an AJAX request from a tab, or a full page request.

Queries with 'X-Remote': true should refresh only the tabbed content, while queries without are normal resources and should refresh the entire page contents

This uses a similar technique to pJax or Rail's turbolinks.

There are a variety of settings for configuring dynamic content behavior. Visit the tab settings section for more information
$('.dynamic.example .menu .item') .tab({ context : '.dynamic.example', auto : true, path : '/modules/tab.html' }) ;

...with an API Behavior

Tabs provide an optional coupling with API which allow you to specify a templated API endpoint that a tab can query

Tabs will automatically pass the url variable {$tab} which can be replaced for RESTful API links.

To learn more about API behaviors built into semantic check out the API docs

View API Docs


All the following behaviors can be called using the syntax $('.foo').tab('behavior name', argumentOne, argumentTwo)
attach events(selector, event) Attaches tab action to given selector. Default event if none specified is toggle
change tab(path) Changes tab to path
set state(path) Sets current path to state
get path Returns current path
is tab Returns whether tab exists
cache read(path) Returns cached HTML for path
cache add(path, html) Sets cached HTML for path
cache remove(path) Removes cached HTML for path

Tab Settings
Form settings modify the tab behavior

Setting Default Description
auto false Whether tab should load remote content as same url as history
deactivate 'siblings' When set to siblings will only deactivate elements that are DOM siblings with the activated element. When set to all the component will deactivate all other elements initialized at the same time.
history false Whether to record history events for tab changes
ignoreFirstLoad false Do not load content remotely on first tab load. Useful when open tab is rendered on server.
evaluateScripts once Whether inline scripts in tab HTML should be parsed on tab load. Defaults to once, parsing only on first load. Can also be set to true or false to always parse or never parse inline scripts.
alwaysRefresh false Tab should reload content every time it is opened
siblings Can be set to either siblings or all. Siblings will only de-activate tab activators that are siblings of the clicked element when a tab is selected. All will deactivate all other tab activators initialized at the same time.
response Can be set to either response, DOM or html. Using DOM will cache the a clone of the DOM tree, preserving all events as they existed on render. response will cache the original response on load, this way callbacks always receive the same content. Using html will cache the resulting html after all callbacks, making sure any changes to content are preserved.
cache true Tab should cache content after loading locally to avoid server trip on second load
apiSettings false Settings object for $.api call
historyType hash Can be set to hash or state. Hash will use an in-page link to create history events. State will use DOM History and load pages from server on refresh.
path false When using historyType state you must specify the base URL for all internal links.
context false Tabs are limited to those found inside this context
childrenOnly false If enabled limits tabs to children of passed context
maxDepth 25 Maximum amount of nested tabs allowed (avoids recursion)


Callbacks specify a function to occur after a specific behavior.

Parameters Context Description
onFirstLoad tabPath, parameterArray, historyEvent Tab Callback only the first time a tab is loaded
onLoad tabPath, parameterArray, historyEvent Tab Callback every time a tab is loaded
onRequest tabPath Tab Called when a tab begins loading remote content
onVisible tabPath Tab Called after a tab becomes visible

DOM Settings
DOM settings specify how this module should interface with the DOM

Setting Default Description
namespace tab Event namespace. Makes sure module teardown does not effect other events attached to an element.
templates : { // returns page title determineTitle: function(tabArray) {} }
Functions used to return content
selector : { tabs : '', parent : '.ui:not(.menu)' }
Selectors used by module
metadata : { tab : 'tab', loaded : 'loaded', promise: 'promise' }
DOM metadata used by module
className : { loading : 'loading', active : 'active' }
Class names used to attach style to state

Debug Settings
Debug settings controls debug output to the console

Setting Default Description
name Tab Name used in debug logs
silent False Silences all console output including error messages, regardless of other debug settings.
debug False Provides standard debug output to console
performance True Provides standard debug output to console
verbose True Provides ancillary debug output to console
error: { api : 'You attempted to load content without API module', method : 'The method you called is not defined', missingTab : 'Activated tab cannot be found for this context.', noContent : 'The tab you specified is missing a content url.', path : 'History enabled, but no path was specified', recursion : 'Max recursive depth reached', state : 'The state library has not been initialized' }

Dimmer Message
Dimmer sub-header