Menu

Tab

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

Download

Type

Tab

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.

States

Active

A tab can be activated, and visible on the page

Loading

A tab can display a loading indicator

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.
First
Second
Third
$('.menu .item') .tab() ;

Retreiving Remote Tab Content

Using auto: true will load the tab's path from your server with additional headers to specify an in-page request. Additional requests will automatically be loaded from cache without a server request.

API requests for the following example have been faked using SinonJS to avoid network overhead.
$('.dynamic.example .menu .item') .tab({ context : '.dynamic.example', auto : true, path : '/' }) ;

AJAX Tab One

Multiple Tabs on Same Page

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.
1A
1B
1C
2A
2B
2C
3A
3B
3C
4A
4B
4C
5A
5B
5C
6A
6B
6C
$('#context1 .menu .item') .tab({ context: $('#context1') }) ; $('#context2 .menu .item') .tab({ context: $('#context2') }) ;

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' }) ;
1A
1B
1C
2A
2B
2C
3A
3B
3C

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 }) ;
1A
1B
1C
2A
2B
2C
3A
3B
3C

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.

$('.tabular.menu .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.

$('.ui.menu .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.

$('.ui.menu .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 apprpopriate content.

$('.ui.menu .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

Behavior

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 set(path) 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
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.
alwaysRefresh false Tab should reload content every time it is opened
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
mayDepth 25 Maximum amount of nested tabs allowed (avoids recursion)

Callbacks

Callbacks specify a function to occur after a specific behavior.

Parameters Context Description
onTabInit tabPath, parameterArray, historyEvent Tab Callback only the first time a tab is loaded
onTabLoad tabPath, parameterArray, historyEvent Tab Callback every time a tab is loaded

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
templates : { // returns page title determineTitle: function(tabArray) {} }
Functions used to return content
selector
selector : { tabs : '.ui.tab', parent : '.ui:not(.menu)' }
Selectors used by module
metadata
metadata : { tab : 'tab', loaded : 'loaded', promise: 'promise' }
DOM metadata used by module
className
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
debug False Provides standard debug output to console
performance True Provides standard debug output to console
verbose True Provides ancillary debug output to console
errors
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