jQuery UI Tabs

Overview

Tabs are generally used to break content into multiple sections that can be swapped to save space, much like an accordion.

By default a tab widget will swap between tabbed sections onClick, but the events can be changed to onHover through an option. Tab content can be loaded via Ajax by setting an href on a tab.

NOTE: Tabs created dynamically using .tabs( "add", ... ) are given an id of ui-tabs-NUM, where NUM is an auto-incrementing id. If you use this naming convention for your own elements, you may encounter problems.

Contents

[edit]

Events

A series of events fire when interacting with a tabs interface:

  • tabsselect, tabsload, tabsshow (in that order)
  • tabsadd, tabsremove
  • tabsenable, tabsdisable

Event binding example: 

$('#example').bind('tabsselect', function(event, ui) {

    // Objects available in the function context:
    ui.tab     // anchor element of the selected (clicked) tab
    ui.panel   // element, that contains the selected/clicked tab contents
    ui.index   // zero-based index of the selected (clicked) tab

});

Note that if a handler for the tabsselect event returns false, the clicked tab will not become selected (useful for example if switching to the next tab requires a form validation).

[edit]

Ajax mode

Tabs supports loading tab content via Ajax in an unobtrusive manner.

The HTML you need is slightly different from the one that is used for static tabs: A list of links pointing to existing resources (from where the content gets loaded) and no additional containers at all (unobtrusive!). The containers' markup is going to be created on the fly: 

<div id="example">
     <ul>
         <li><a href="ahah_1.html"><span>Content 1</span></a></li>
         <li><a href="ahah_2.html"><span>Content 2</span></a></li>
         <li><a href="ahah_3.html"><span>Content 3</span></a></li>
     </ul>
</div>

Obviously this degrades gracefully - the links, e.g. the content, will still be accessible with JavaScript disabled.

Note that if you wish to reuse an existing container, you could do so by matching a title attribute and the container's id: 

<li><a href="hello/world.html" title="Todo Overview"> ... </a></li>

and a container like: 

<div id="Todo_Overview"> ... </div>

(Note how white space is replaced with an underscore)

This is useful if you want a human readable hash in the URL instead of a cryptic generated one.

[edit]

Back button and bookmarking

Tabs 2 already supported this functionality, although the history plugin needs a rewrite first (it doesn't support Safari 3 and is in general a little inflexible) before it can be build back into the tabs. It is planned and Klaus is working on it whenever he finds the time. Actual bugs in the UI Tabs plugin itself always have higher priority though.

[edit]

How to...

[edit]

...retrieve the index of the currently selected tab

var $tabs = $('#example').tabs();
var selected = $tabs.tabs('option', 'selected'); // => 0
[edit]

...open links in the current tab instead of leaving the page

"Hijax" links after tab content has been loaded: 

$('#example').tabs({
    load: function(event, ui) {
        $('a', ui.panel).click(function() {
            $(ui.panel).load(this.href);
            return false;
        });
    }
});
[edit]

...select a tab from a text link instead of clicking a tab itself

var $tabs = $('#example').tabs(); // first tab selected

$('#my-text-link').click(function() { // bind click event to link
    $tabs.tabs('select', 2); // switch to third tab
    return false;
});
[edit]

...prevent switching to the tab on click depending on form validation

Returning false in the tabs select handler prevents the clicked tab from becoming selected. 

$('#example').tabs({
    select: function(event, ui) {
        var isValid = ... // form validation returning true or false
        return isValid;
    }
});
[edit]

...immediately select a just added tab

var $tabs = $('#example').tabs({
    add: function(event, ui) {
        $tabs.tabs('select', '#' + ui.panel.id);
    }
});
[edit]

...follow a tab's URL instead of loading its content via ajax

Note that opening a tab in a new window is unexpected, e.g. inconsistent behaviour exposing a usablity problem (http://www.useit.com/alertbox/tabs.html). 

$('#example').tabs({
    select: function(event, ui) {
        var url = $.data(ui.tab, 'load.tabs');
        if( url ) {
            location.href = url;
            return false;
        }
        return true;
    }
});


[edit]

...prevent a FOUC (Flash of Unstyled Content) before tabs are initialized

Add the necessary classes to hide an inactive tab panel to the HTML right away - note that this will not degrade gracefully with JavaScript being disabled: 

<div id="example" class="ui-tabs">
  ...
  <div id="a-tab-panel" class="ui-tabs-hide"> </div>
  ...
</div>
[edit]

Why does...

[edit]

...my slider, Google Map, sIFR etc. not work when placed in a hidden (inactive) tab?

Any component that requires some dimensional computation for its initialization won't work in a hidden tab, because the tab panel itself is hidden via display: none so that any elements inside won't report their actual width and height (0 in most browsers).

There's an easy workaround. Use the off-left technique for hiding inactive tab panels. E.g. in your style sheet replace the rule for the class selector ".ui-tabs .ui-tabs-hide" with 

.ui-tabs .ui-tabs-hide {
    position: absolute;
    left: -10000px;
}

For Google maps you can also resize the map once the tab is displayed like this: 

$('#example').bind('tabsshow', function(event, ui) {
    if (ui.panel.id == "map-tab") {
        resizeMap();
    }
});
resizeMap() will call Google Maps' checkResize() on the particular map.

Dependencies

  • UI Core
  • To use the cookie option: jquery.cookie.js
  • Required CSS: 
    .ui-tabs .ui-tabs-hide {
     display: none;
}

Example

A simple jQuery UI Tabs.

$("#tabs").tabs();


<!DOCTYPE html>
<html>
<head>
  <link href="http://ajax.googleapis.com/ajax/libs/jqueryui/1.8/themes/base/jquery-ui.css" rel="stylesheet" type="text/css"/>
  <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.4/jquery.min.js"></script>
  <script src="http://ajax.googleapis.com/ajax/libs/jqueryui/1.8/jquery-ui.min.js"></script>
  
  <script>
  $(document).ready(function() {
    $("#tabs").tabs();
  });
  </script>
</head>
<body style="font-size:62.5%;">
  
<div id="tabs">
    <ul>
        <li><a href="#fragment-1"><span>One</span></a></li>
        <li><a href="#fragment-2"><span>Two</span></a></li>
        <li><a href="#fragment-3"><span>Three</span></a></li>
    </ul>
    <div id="fragment-1">
        <p>First tab is active by default:</p>
        <pre><code>$('#example').tabs();</code></pre>
    </div>
    <div id="fragment-2">
        Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat.
        Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat.
    </div>
    <div id="fragment-3">
        Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat.
        Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat.
        Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat.
    </div>
</div>
</body>
</html>

Options

Events

Methods

Theming

The jQuery UI Tabs plugin uses the jQuery UI CSS Framework to style its look and feel, including colors and background textures. We recommend using the ThemeRoller tool to create and download custom themes that are easy to build and maintain.

If a deeper level of customization is needed, there are widget-specific classes referenced within the jquery.ui.tabs.css stylesheet that can be modified. These classes are highlighed in bold below.

Sample markup with jQuery UI CSS Framework classes

<div class="ui-tabs ui-widget ui-widget-content ui-corner-all" id="tabs">
   <ul class="ui-tabs-nav ui-helper-reset ui-helper-clearfix ui-widget-header ui-corner-all">
     <li class="ui-state-default ui-corner-top ui-tabs-selected ui-state-active"><a href="#tabs-1">Nunc tincidunt</a></li>
      <li class="ui-state-default ui-corner-top"><a href="#tabs-2">Proin dolor</a></li>
   <div class="ui-tabs-panel ui-widget-content ui-corner-bottom" id="tabs-1">
      <p>Tab one content goes here.</p>
   </div>
    ...
</div>

Note: This is a sample of markup generated by the tabs plugin, not markup you should use to create a tabs. The only markup needed for that is
<div id="tabs">
   <ul>
      <li><a href="#tabs-1">Nunc tincidunt</a></li>
      <li><a href="#tabs-2">Proin dolor</a></li>
      <li><a href="#tabs-3">Aenean lacinia</a></li>
   </ul>
   <div id="tabs-1">
      <p>Tab 1 content</p>
   </div>
   <div id="tabs-2">
      <p>Tab 2 content</p>
   </div>
   <div id="tabs-3">
      <p>Tab 3 content</p>
   </div>
</div>.