jQuery TOOLS / Tabs - Tabs done right

• First tab
• Second tab
• Third tab

Tab pane 1. Here you can see tabs in action. They are the most popular user-interface component on the web. And for good reason: they are intuitive to use, people are used to them, and above all your can organize your pages in a more user-friendly way.

Tab pane 2. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae; Sed lorem. Aenean commodo pede a eros volutpat viverra. Pellentesque a nisl. Nullam et metus.

Tab pane 3. Praesent dictum, velit vel adipiscing suscipit, metus nisl lobortis sem, nec elementum nibh urna non turpis. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae.

Motivation

Here are the highlights:

• Simple to use. You need a single line of JavaScript to get started. There are no redundant features.
• An effect framework which can be used to implement vertical accordions, horizontal accordions and more.
• Built-in effects which include: default, fade, slide, ajax and horizontal and you can easily make your own effects or modify the existing default effects.
• Plugin framework Built-in plugins include: slideshow and history and you can easily make your own plugins.
• Cross linking. If the tab content areas contain any anchor links to other tab's content areas, the correct tab is automatically opened when those links are clicked.
• Lightweight. The JavaScript file is only 2.9 Kb when minified. Compare this to the jQuery UI library where you'll have to have 130 Kb of minified code to get tabs and accordions working.

This tool uses a simple and natural syntax and has an advanced programming API. You can extend it with callback methods or with your own plugins. This tool has a similar structure and feel as the other tools. Learn to use this tool and you will know how to use the rest.

This tool is a mature project and is actively maintained. The source code is clean, professional and easy to follow. It passes Douglas Crockford's JavaScript Verifier and it it doesn't assign any global variables. Active forums keep this tool alive and you can expect to see new releases coming out in the future.

Usage

We believe that the best way to learn is through demos. The following demos are fully documented and a standalone page is provided to get tabs working on your site. It's really important to study the first demo, "Minimal setup for tabs", because it teaches you the basics of using the library.

• Minimal setup for tabs
• Naming the tabs
• 4 different skins with CSS
• Loading tab contents with AJAX
• Handling browsers back button
• AJAX:ed tabs with History support
• Using mouseover to switch tabs
• Making Wizards with the Tabs
• Making Accordions with the Tabs
• Customizing the Accordion effect
• Horizontal Accordion using the Tabs
• Multiple Tabs and Accordion instances
• Slideshow plugin for the Tabs

For the impatient

Here is the minimal HTML code to get tabs working:

<!-- the tabs -->
<ul>
	<li><a href="#">Tab 1</a></li>
	<li><a href="#">Tab 2</a></li>
	<li><a href="#">Tab 3</a></li>
</ul>

<!-- tab "panes" -->
<div class="panes">
	<div>pane 1 content</div>
	<div>pane 2 content</div>
	<div>pane 3 content</div>
</div>

JavaScript setup

This JavaScript snippet activates those tabs:

// setup ul.tabs to work as tabs for each div directly under div.panes
$("ul.tabs").tabs("div.panes > div");

The rest is CSS coding. Look at the standalone version and its source code to get things working on your site.

tabs Graphics

You can use our graphics as the basis for your design. You can freely change the design as you see fit. Click the image on the right to download a zip file. Before using the graphics, you should consult the User's Guide on how graphics can be used when designing the look and feel of the tools.

Here are a few examples of what is included in the zip file:

Configuration

There are many other ways of using this tool than the demos provided above. Here is a generic form for constructing tabs:

$("<tabs_selector>").tabs("<pane_selector>", {
	/* tabs configuration goes here */

	// first configuration property
	event: 'mouseover',

	// another property
	effect: 'slide',

	// ... the rest of the configuration properties
});

tabs_selector

You select one or more root elements for the tabs with the tabs_selector which is a jQuery selector. The root element is a container for individual tabs. By default, the tool searches for A tags inside the root element that will work as individual tabs. This can be changed with the tabs configuration option. The root element can be any HTML element such as DIV, UL, DL or TABLE.

1^st argument: pane_selector

In Tabs terminology, the content areas for tabs are called "panes". The pane_selector selects the content areas that correspond to the individual tabs. For example, a selector: div.panes > div selects all DIV elements that are direct children of the DIV.panes element. The first pane is assigned to the first tab and second to the second tab and so on. This selector does not select any root element and it should return as many elements as you have tabs.

The value for this argument can also be a jQuery object that contains the required panes.

2^nd argument: configuration

The second argument for the initialization call is the configuration object. It can be either a function in which case it will correspond to an onBeforeClick event listener or it can be a complex object with many different configuration options. Here is a full list of available options:

Note: If you want to instantiate multiple tabs with the same call then you should read this.

Initializing multiple Tabs

Typically you have one Tabs instance on your page and your panes can be placed anywhere on the page. It is possible to instantiate multiple Tabs with the same call. For example, if you have multiple root elements with a CSS class name "tabs", they can all be instantiated like this:

$(".tabs").tabs(".panes > div");

So how do we know which panes belong to which tabs? The solution is to enclose each tab/pane combination inside a wrapper element. For example:

<!-- 1st Tabs and associative panes inside a wrapping DIV element -->
<div>
	<ul class="tabs">
		...
	</ul>

	<div class="panes">
		...
	</div>
</div>

<!-- 2nd Tabs and accociative panes inside a wrapping DIV element -->
<div>
	<ul class="tabs">
		...
	</ul>

	<div class="panes">
		...
	</div>
</div>

Now all Tabs will work individually. Note that instantiating Tabs with one call as in above example is defferent than doing multiple separate identical calls. Of course you can always instantiate your Tabs separately but you need to supply different selector for the panes. For example:

// two Tabs instantiation calls with different selectors
$("#tabs1").tabs("#panes1 > div");
$("#tabs2").tabs("#panes2 > div");

// done.

On accordion setups you typically have a common root element for both the tabs and the panes so there is no need for a separate wrapper element. You should take a look at the demo about Multiple Tabs and Accordion instances.

Using callback functions

This tool supports two callback functions: onBeforeClick and onClick. Inside these callback functions the this variable is a pointer to the scripting API.

The first argument for the callback function is the Event object and the second argument is the index number of the tab being clicked. Here is an example of an onBeforeClick callback function:

$("ul.tabs").tabs({

	// add a class "current" to the active pane
	onBeforeClick: function(event, tabIndex) {
		this.getCurrentPane().addClass("current");
	}

});

See the Using Callback Functions section from the User's Guide for a more detailed description about this important topic.

Scripting API

This tool has a useful API for scripters. A lot of effort has been put into it so that you can enrich the tabbing experience. You can get a handle to the API in numerous ways as described in the User's Manual. Here is an example of how to access the API:

// get handle to the api (must have been constructed before this call)
var api = $("ul.tabs").tabs()

// advance to the next tab
api.next();

// send google analytics when tabs are clicked
api.onClick(function(index) {
	_tracker._trackEvent("Documentation", "Tabs", "tab " + index);
});

Here is a list of all API methods:

Making custom effects

If you want to make custom effects you should use the $.tools.tabs.addEffect method. This method is "static", meaning that you don't have to have the the tabs API (or instance) already loaded. You can add effects before any tabs are constructed.

This method accepts two arguments. The first argument is the effect name and the second argument is the function that performs the required functionality when a tab (or accordion header) is clicked. You can use this method to modify existing effects or add new ones. Here is an example:

// adds an effect called "myEffect" to tabs
$.tools.tabs.addEffect("myEffect", function(tabIndex, done) {

	/* here you'll write your effect. the 'this' variable points to the API */

});

Your effect function is given two arguments. First, tabIndex, is the tab index number and the second, done, is a function that you must call after your effect finishes its job. This can be accomplished by calling done.call(); .

The default effect

Effects are actually quite easy to implement. The default effect, for example, does the following:

$.tools.tabs.addEffect("default", function(tabIndex, done) {

	// hide all panes and show the one that is clicked
	this.getPanes().hide().eq(tabIndex).show();

	// the supplied callback must be called after the effect has finished its job
	done.call();
});

Look in the tab's source code for more examples of the available effects. The basic idea is to use your jQuery skills together with the API methods. Here you can see a demo about a custom accordion effect.

Plugins

tabs.slideshow

The slideshow plugin provides an automatic switching between tabs. It advances to the next tab in pre-configured intervals. Here is a slideshow plugin in action:

First pane

Aenean nec imperdiet ligula. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus.

Suspendisse potenti. Sed elementum risus eleifend massa vestibulum consectetur. Duis massa augue, aliquam eget fringilla vel, aliquam vitae arcu. Nam sed magna mi. Praesent odio neque, dapibus sit amet suscipit at, tempus sed nibh. Aliquam sagittis ligula in ligula faucibus cursus. Quisque vulputate pellentesque facilisis.

Second pane

Consectetur adipiscing elit. Praesent bibendum eros ac nulla. Integer vel lacus ac neque viverra.

Vivamus euismod euismod sagittis. Etiam cursus neque non lectus mattis cursus et a libero. Vivamus condimentum hendrerit metus, a sollicitudin magna vulputate eu. Donec sed tincidunt lectus. Donec tellus lectus, fermentum sit amet porta non, rhoncus ac mi. Quisque placerat auctor justo, a egestas urna tincidunt eleifend.

Third pane

Non lectus lacinia egestas. Nulla hendrerit, felis quis elementum viverra, purus felis egestas magna.

Aenean elit lorem, pretium vitae dictum in, fermentum consequat dolor. Proin consectetur sollicitudin tellus, non elementum turpis pharetra non. Sed quis tellus quam.

Highlights

• Easy configuration of the "previous tab" and "next tab" actions without any JavaScript. These buttons can easily be hidden when there is no next or previous tab available.
• When you mouseover the tab elements, the automatic switching is paused.
• By default the next slide is shown when the active pane is clicked; however, this can be changed in the configuration.

Usage

The best way to learn is to study the full documentation for the example above. For the impatient here is the JavaScript setup:

$("div.tabs").tabs(".images > div", {

		// enable "cross-fading" effect
		effect: 'fade',
		fadeOutSpeed: "slow",

		// start from the beginning after the last tab
		rotate: true

	// use the slideshow plugin. It accepts its own configuration
	}).slideshow();

Configuration

Here is a full list of available configuration options:

JavaScript API

The following methods are added to the main JavaScript API of the tabs and they are ready to be used after the plugin has been installed.

tabs.history

History plugin enables history support for the tabs. This means that when the user clicks on the browser's back and forward buttons, the tool will navigate between the tabs and will not jump to another page. Use the following tabs together with back/forward buttons to see it in action:

• The Player
• Plugins
• Streaming
• Scripting

Lorem ipsum dolor sit amet

Consectetur adipiscing elit. Duis viverra, leo sit amet auctor fermentum, risus lorem posuere tortor, in accumsan purus magna imperdiet sem.

Suspendisse enim. Pellentesque facilisis aliquam enim. Maecenas facilisis molestie lectus. Sed ornare ultricies tortor. Vivamus nibh metus, faucibus quis, semper ut, dignissim id, diam.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis viverra, leo sit amet auctor fermentum, risus lorem posuere tortor, in accumsan purus magna imperdiet sem.

Lorem ipsum dolor sit amet

Suspendisse enim. Pellentesque facilisis aliquam enim. Maecenas facilisis molestie lectus. Sed ornare ultricies tortor. Vivamus nibh metus, faucibus quis, semper ut, dignissim id, diam.

Mauris ultricies. Nam feugiat egestas nulla. Donec augue dui, molestie sed, tristique sit amet, blandit eu, turpis. Mauris hendrerit, nisi et sodales tempor, orci tellus laoreet elit, sed molestie dui quam vitae dui.

Pellentesque nisl. Ut adipiscing vehicula risus. Nam eget tortor. Maecenas id augue. Vivamus interdum nulla ac dolor. Fusce metus. Suspendisse eu purus. Maecenas quis lacus eget dui volutpat molestie.

Title for the third tab pane

Mauris ultricies. Nam feugiat egestas nulla. Donec augue dui, molestie sed, tristique sit amet, blandit eu, turpis. Mauris hendrerit, nisi et sodales tempor, orci tellus laoreet elit, sed molestie dui quam vitae dui.

Pellentesque nisl. Ut adipiscing vehicula risus. Nam eget tortor. Maecenas id augue. Vivamus interdum nulla ac dolor. Fusce metus. Suspendisse eu purus. Maecenas quis lacus eget dui volutpat molestie.

Fourth pane is here

Maecenas at odio. Nunc laoreet lectus vel ante. Nullam imperdiet. Sed justo dolor, mattis eu, euismod sed, tempus a, nisl. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus.

In sed dolor. Etiam eget quam ac nibh pharetra adipiscing. Nullam vitae ligula. Sed sit amet leo sit amet arcu mollis ultrices. Vivamus rhoncus sapien nec lorem. In mattis nisi. Vivamus at enim. Integer semper imperdiet massa. Vestibulum nulla massa, pretium quis, porta id, vestibulum vitae, velit.

Usage

The best way to learn is to study the full documentation for the example above. For the impatient here is the JavaScript setup:

$(function() {
	$("#flowtabs").tabs("#flowpanes > div").history();
});

onHash utility plugin

This plugin comes coupled with a general purpose jQuery plugin called onHash that you can use to get a handle to the browser's back button in a cross-browser manner. Here is how you can use it:

$("a.history").onHash(function(event, hash) {

});

You select a bunch of anchor tags from your page and supply a callback function that is called whenever the browser's back (or forward) button is pressed. The callback is only called when the browser navigates to any of the locations that are specified in the links' href attribute. Those href attributes must be anchor links; i.e. they start with the # character.

The callback is fed with two arguments. The first one is the jQuery event object and the second one is the anchor link (also called a hash) where the browser is navigating to.

Release Notes

  follow jQuery Tools on