Tabs Widget

Categories: Widgets

Tabs Widgetversion added: 1.0

Description: A single content area with multiple panels, each associated with a header in a list.

QuickNavExamples

Options

Methods


Extension Points

Events

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

Tabs have a particular set of markup that must be used in order for them to work properly:

  • The tabs themselves must be in either an ordered (<ol>) or unordered (<ul>) list
  • Each tab "title" must be inside of a list item (<li>) and wrapped by an anchor (<a>) with an href attribute
  • Each tab panel may be any valid element but it must have an id which corresponds to the hash in the anchor of the associated tab.

The content for each tab panel can be defined in-page or can be loaded via Ajax; both are handled automatically based on the href of the anchor associated with the tab. By default tabs are activated on click, but the events can be changed to hover via the event option.

Below is some sample markup:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
 
<div id="tabs">
  <ul>
    <li><a href="#fragment-1">One</a></li>
    <li><a href="#fragment-2">Two</a></li>
    <li><a href="#fragment-3">Three</a></li>
  </ul>
  <div id="fragment-1">
    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-2">
    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.
  </div>
</div>

Keyboard interaction

When focus is on a tab, the following key commands are available:

  • UP/LEFT: Move focus to the previous tab. If on first tab, moves focus to last tab. Activate focused tab after a short delay.
  • DOWN/RIGHT: Move focus to the next tab. If on last tab, moves focus to first tab. Activate focused tab after a short delay.
  • CTRL + UP/LEFT: Move focus to the previous tab. If on first tab, moves focus to last tab. The focused tab must be manually activated.
  • CTRL + DOWN/RIGHT: Move focus to the next tab. If on last tab, moves focus to first tab. The focused tab must be manually activated.
  • HOME: Move focus to the first tab. Activate focused tab after a short delay.
  • END: Move focus to the last tab. Activate focused tab after a short delay.
  • CTRL + HOME: Move focus to the first tab. The focused tab must be manually activated.
  • CTRL + END: Move focus to the last tab. The focused tab must be manually activated.
  • SPACE: Activate panel associated with focused tab.
  • ENTER: Activate or toggle panel associated with focused tab.
  • ALT/OPTION + PAGE UP: Move focus to the previous tab and immediately activate.
  • ALT/OPTION + PAGE DOWN: Move focus to the next tab and immediately activate.

When focus is in a panel, the following key commands are available:

  • CTRL + UP: Move focus to associated tab.
  • ALT/OPTION + PAGE UP: Move focus to the previous tab and immediately activate.
  • ALT/OPTION + PAGE DOWN: Move focus to the next tab and immediately activate.

Theming

The tabs widget uses the jQuery UI CSS framework to style its look and feel. If tabs specific styling is needed, the following CSS class names can be used:

  • ui-tabs: The outer container of the tabs. This element will additionally have a class of ui-tabs-collapsible when the collapsible option is set.
    • ui-tabs-nav: The list of tabs.
      • The active list item in the nav will have a ui-tabs-active class. Any list item whose associated content is loading via an Ajax call will have a ui-tabs-loading class.
        • ui-tabs-anchor: The anchors used to switch panels.
    • ui-tabs-panel: The panels associated with the tabs. Only the panel whose corresponding tab is active will be visible.

Dependencies

Additional Notes:

  • This widget requires some functional CSS, otherwise it won't work. If you build a custom theme, use the widget's specific CSS file as a starting point.

Options

active 

Type: Boolean or Integer
Default: 0
Which panel is currently open.
Multiple types supported:
  • Boolean: Setting active to false will collapse all panels. This requires the collapsible option to be true.
  • Integer: The zero-based index of the panel that is active (open). A negative value selects panels going backward from the last panel.
Code examples:

Initialize the tabs with the active option specified:

1
2
3
 
$( ".selector" ).tabs({
  active: 1
});

Get or set the active option, after initialization:

1
2
3
4
5
 
// Getter
var active = $( ".selector" ).tabs( "option", "active" );
 
// Setter
$( ".selector" ).tabs( "option", "active", 1 );

collapsible 

Type: Boolean
Default: false
When set to true, the active panel can be closed.
Code examples:

Initialize the tabs with the collapsible option specified:

1
2
3
 
$( ".selector" ).tabs({
  collapsible: true
});

Get or set the collapsible option, after initialization:

1
2
3
4
5
 
// Getter
var collapsible = $( ".selector" ).tabs( "option", "collapsible" );
 
// Setter
$( ".selector" ).tabs( "option", "collapsible", true );

disabled 

Type: Boolean or Array
Default: false
Which tabs are disabled.
Multiple types supported:
  • Boolean: Enable or disable all tabs.
  • Array: An array containing the zero-based indexes of the tabs that should be disabled, e.g., [ 0, 2 ] would disable the first and third tab.
Code examples:

Initialize the tabs with the disabled option specified:

1
2
3
 
$( ".selector" ).tabs({
  disabled: [ 0, 2 ]
});

Get or set the disabled option, after initialization:

1
2
3
4
5
 
// Getter
var disabled = $( ".selector" ).tabs( "option", "disabled" );
 
// Setter
$( ".selector" ).tabs( "option", "disabled", [ 0, 2 ] );

event 

Type: String
Default: "click"
The type of event that the tabs should react to in order to activate the tab. To activate on hover, use "mouseover".
Code examples:

Initialize the tabs with the event option specified:

1
2
3
 
$( ".selector" ).tabs({
  event: "mouseover"
});

Get or set the event option, after initialization:

1
2
3
4
5
 
// Getter
var event = $( ".selector" ).tabs( "option", "event" );
 
// Setter
$( ".selector" ).tabs( "option", "event", "mouseover" );

heightStyle 

Type: String
Default: "content"
Controls the height of the tabs widget and each panel. Possible values:
  • "auto": All panels will be set to the height of the tallest panel.
  • "fill": Expand to the available height based on the tabs' parent height.
  • "content": Each panel will be only as tall as its content.
Code examples:

Initialize the tabs with the heightStyle option specified:

1
2
3
 
$( ".selector" ).tabs({
  heightStyle: "fill"
});

Get or set the heightStyle option, after initialization:

1
2
3
4
5
 
// Getter
var heightStyle = $( ".selector" ).tabs( "option", "heightStyle" );
 
// Setter
$( ".selector" ).tabs( "option", "heightStyle", "fill" );

hide 

Type: Boolean or Number or String or Object
Default: null
If and how to animate the hiding of the panel.
Multiple types supported:
  • Boolean: When set to false, no animation will be used and the panel will be hidden immediately. When set to true, the panel will fade out with the default duration and the default easing.
  • Number: The panel will fade out with the specified duration and the default easing.
  • String: The panel will be hidden using the specified effect. The value can either be the name of a built-in jQuery animation method, such as "slideUp", or the name of a jQuery UI effect, such as "fold". In either case the effect will be used with the default duration and the default easing.
  • Object: If the value is an object, then effect, delay, duration, and easing properties may be provided. If the effect property contains the name of a jQuery method, then that method will be used; otherwise it is assumed to be the name of a jQuery UI effect. When using a jQuery UI effect that supports additional settings, you may include those settings in the object and they will be passed to the effect. If duration or easing is omitted, then the default values will be used. If effect is omitted, then "fadeOut" will be used. If delay is omitted, then no delay is used.
Code examples:

Initialize the tabs with the hide option specified:

1
2
3
 
$( ".selector" ).tabs({
  hide: { effect: "explode", duration: 1000 }
});

Get or set the hide option, after initialization:

1
2
3
4
5
 
// Getter
var hide = $( ".selector" ).tabs( "option", "hide" );
 
// Setter
$( ".selector" ).tabs( "option", "hide", { effect: "explode", duration: 1000 } );

show 

Type: Boolean or Number or String or Object
Default: null
If and how to animate the showing of the panel.
Multiple types supported:
  • Boolean: When set to false, no animation will be used and the panel will be shown immediately. When set to true, the panel will fade in with the default duration and the default easing.
  • Number: The panel will fade in with the specified duration and the default easing.
  • String: The panel will be shown using the specified effect. The value can either be the name of a built-in jQuery animation method, such as "slideDown", or the name of a jQuery UI effect, such as "fold". In either case the effect will be used with the default duration and the default easing.
  • Object: If the value is an object, then effect, delay, duration, and easing properties may be provided. If the effect property contains the name of a jQuery method, then that method will be used; otherwise it is assumed to be the name of a jQuery UI effect. When using a jQuery UI effect that supports additional settings, you may include those settings in the object and they will be passed to the effect. If duration or easing is omitted, then the default values will be used. If effect is omitted, then "fadeIn" will be used. If delay is omitted, then no delay is used.
Code examples:

Initialize the tabs with the show option specified:

1
2
3
 
$( ".selector" ).tabs({
  show: { effect: "blind", duration: 800 }
});

Get or set the show option, after initialization:

1
2
3
4
5
 
// Getter
var show = $( ".selector" ).tabs( "option", "show" );
 
// Setter
$( ".selector" ).tabs( "option", "show", { effect: "blind", duration: 800 } );

Methods

destroy()Returns: jQuery (plugin only)

Removes the tabs functionality completely. This will return the element back to its pre-init state.
  • This method does not accept any arguments.
Code examples:

Invoke the destroy method:

1
 
$( ".selector" ).tabs( "destroy" );

disable()Returns: jQuery (plugin only)

Disables all tabs.
  • This signature does not accept any arguments.
Code examples:

Invoke the method:

1
 
$( ".selector" ).tabs( "disable" );

disable( index )Returns: jQuery (plugin only)

Disables a tab. The selected tab cannot be disabled. To disable more than one tab at once, set the disabled option: $( "#tabs" ).tabs( "option", "disabled", [ 1, 2, 3 ] ).
  • index
    Type: Number
    The zero-based index of the tab to disable.
Code examples:

Invoke the method:

1
 
$( ".selector" ).tabs( "disable", 1 );

disable( href )Returns: jQuery (plugin only)

Disables a tab. The selected tab cannot be disabled.
  • href
    Type: String
    The href of the tab to disable.
Code examples:

Invoke the method:

1
 
$( ".selector" ).tabs( "disable", "#foo" );

enable()Returns: jQuery (plugin only)

Enables all tabs.
  • This signature does not accept any arguments.
Code examples:

Invoke the method:

1
 
$( ".selector" ).tabs( "enable" );

enable( index )Returns: jQuery (plugin only)

Enables a tab. To enable more than one tab at once reset the disabled property like: $( "#example" ).tabs( "option", "disabled", [] );.
  • index
    Type: Number
    The zero-based index of the tab to enable.
Code examples:

Invoke the method:

1
 
$( ".selector" ).tabs( "enable", 1 );

enable( href )Returns: jQuery (plugin only)

Enables a tab.
  • href
    Type: String
    The href of the tab to enable.
Code examples:

Invoke the method:

1
 
$( ".selector" ).tabs( "enable", "#foo" );

instance()Returns: Object

Retrieves the tabs's instance object. If the element does not have an associated instance, undefined is returned.

Unlike other widget methods, instance() is safe to call on any element after the tabs plugin has loaded.

  • This method does not accept any arguments.
Code examples:

Invoke the instance method:

1
 
$( ".selector" ).tabs( "instance" );

load( index )Returns: jQuery (plugin only)

Loads the panel content of a remote tab.
  • index
    Type: Number
    The zero-based index of the tab to load.
Code examples:

Invoke the method:

1
 
$( ".selector" ).tabs( "load", 1 );

load( href )Returns: jQuery (plugin only)

Loads the panel content of a remote tab.
  • href
    Type: String
    The href of the tab to load.
Code examples:

Invoke the method:

1
 
$( ".selector" ).tabs( "load", "#foo" );

option( optionName )Returns: Object

Gets the value currently associated with the specified optionName.

Note: For options that have objects as their value, you can get the value of a specific key by using dot notation. For example, "foo.bar" would get the value of the bar property on the foo option.

  • optionName
    Type: String
    The name of the option to get.
Code examples:

Invoke the method:

1
 
var isDisabled = $( ".selector" ).tabs( "option", "disabled" );

option()Returns: PlainObject

Gets an object containing key/value pairs representing the current tabs options hash.
  • This signature does not accept any arguments.
Code examples:

Invoke the method:

1
 
var options = $( ".selector" ).tabs( "option" );

option( optionName, value )Returns: jQuery (plugin only)

Sets the value of the tabs option associated with the specified optionName.

Note: For options that have objects as their value, you can set the value of just one property by using dot notation for optionName. For example, "foo.bar" would update only the bar property of the foo option.

  • optionName
    Type: String
    The name of the option to set.
  • value
    Type: Object
    A value to set for the option.
Code examples:

Invoke the method:

1
 
$( ".selector" ).tabs( "option", "disabled", true );

option( options )Returns: jQuery (plugin only)

Sets one or more options for the tabs.
  • options
    Type: Object
    A map of option-value pairs to set.
Code examples:

Invoke the method:

1
 
$( ".selector" ).tabs( "option", { disabled: true } );

refresh()Returns: jQuery (plugin only)

Process any tabs that were added or removed directly in the DOM and recompute the height of the tab panels. Results depend on the content and the heightStyle option.
  • This method does not accept any arguments.
Code examples:

Invoke the refresh method:

1
 
$( ".selector" ).tabs( "refresh" );

widget()Returns: jQuery

Returns a jQuery object containing the tabs container.
  • This method does not accept any arguments.
Code examples:

Invoke the widget method:

1
 
var widget = $( ".selector" ).tabs( "widget" );

Extension Points

The tabs widget is built with the widget factory and can be extended. When extending widgets, you have the ability to override or add to the behavior of existing methods. The following methods are provided as extension points with the same API stability as the plugin methods listed above. For more information on widget extensions, see Extending Widgets with the Widget Factory.

_getList()Returns: jQuery

Determine which list should be converted to tabs. By default the first descendant list is used.
  • This method does not accept any arguments.
Code examples:

Use the list with the class my-tabs or fall back to the default implementation.

1
2
3
4
 
_getList: function() {
  var list = this.element.find( ".my-tabs" );
  return list.length ? list.eq( 0 ) : this._super();
}

Events

activate( event, ui )Type: tabsactivate

Triggered after a tab has been activated (after animation completes). If the tabs were previously collapsed, ui.oldTab and ui.oldPanel will be empty jQuery objects. If the tabs are collapsing, ui.newTab and ui.newPanel will be empty jQuery objects.

Note: Since the activate event is only fired on tab activation, it is not fired for the initial tab when the tabs widget is created. If you need a hook for widget creation use the create event.
  • event
    Type: Event
  • ui
    Type: Object
    • newTab
      Type: jQuery
      The tab that was just activated.
    • oldTab
      Type: jQuery
      The tab that was just deactivated.
    • newPanel
      Type: jQuery
      The panel that was just activated.
    • oldPanel
      Type: jQuery
      The panel that was just deactivated.
Code examples:

Initialize the tabs with the activate callback specified:

1
2
3
 
$( ".selector" ).tabs({
  activate: function( event, ui ) {}
});

Bind an event listener to the tabsactivate event:

1
 
$( ".selector" ).on( "tabsactivate", function( event, ui ) {} );

beforeActivate( event, ui )Type: tabsbeforeactivate

Triggered immediately before a tab is activated. Can be canceled to prevent the tab from activating. If the tabs are currently collapsed, ui.oldTab and ui.oldPanel will be empty jQuery objects. If the tabs are collapsing, ui.newTab and ui.newPanel will be empty jQuery objects.
  • event
    Type: Event
  • ui
    Type: Object
    • newTab
      Type: jQuery
      The tab that is about to be activated.
    • oldTab
      Type: jQuery
      The tab that is about to be deactivated.
    • newPanel
      Type: jQuery
      The panel that is about to be activated.
    • oldPanel
      Type: jQuery
      The panel that is about to be deactivated.
Code examples:

Initialize the tabs with the beforeActivate callback specified:

1
2
3
 
$( ".selector" ).tabs({
  beforeActivate: function( event, ui ) {}
});

Bind an event listener to the tabsbeforeactivate event:

1
 
$( ".selector" ).on( "tabsbeforeactivate", function( event, ui ) {} );

beforeLoad( event, ui )Type: tabsbeforeload

Triggered when a remote tab is about to be loaded, after the beforeActivate event. Can be canceled to prevent the tab panel from loading content; though the panel will still be activated. This event is triggered just before the Ajax request is made, so modifications can be made to ui.jqXHR and ui.ajaxSettings.

Note: Although ui.ajaxSettings is provided and can be modified, some of these properties have already been processed by jQuery. For example, prefilters have been applied, data has been processed, and type has been determined. The beforeLoad event occurs at the same time, and therefore has the same restrictions, as the beforeSend callback from jQuery.ajax().

  • event
    Type: Event
  • ui
    Type: Object
    • tab
      Type: jQuery
      The tab that is being loaded.
    • panel
      Type: jQuery
      The panel which will be populated by the Ajax response.
    • jqXHR
      Type: jqXHR
      The jqXHR object that is requesting the content.
    • ajaxSettings
      Type: Object
      The properties that will be used by jQuery.ajax to request the content.
Code examples:

Initialize the tabs with the beforeLoad callback specified:

1
2
3
 
$( ".selector" ).tabs({
  beforeLoad: function( event, ui ) {}
});

Bind an event listener to the tabsbeforeload event:

1
 
$( ".selector" ).on( "tabsbeforeload", function( event, ui ) {} );

create( event, ui )Type: tabscreate

Triggered when the tabs are created. If the tabs are collapsed, ui.tab and ui.panel will be empty jQuery objects.
Code examples:

Initialize the tabs with the create callback specified:

1
2
3
 
$( ".selector" ).tabs({
  create: function( event, ui ) {}
});

Bind an event listener to the tabscreate event:

1
 
$( ".selector" ).on( "tabscreate", function( event, ui ) {} );

load( event, ui )Type: tabsload

Triggered after a remote tab has been loaded.
  • event
    Type: Event
  • ui
    Type: Object
    • tab
      Type: jQuery
      The tab that was just loaded.
    • panel
      Type: jQuery
      The panel which was just populated by the Ajax response.
Code examples:

Initialize the tabs with the load callback specified:

1
2
3
 
$( ".selector" ).tabs({
  load: function( event, ui ) {}
});

Bind an event listener to the tabsload event:

1
 
$( ".selector" ).on( "tabsload", function( event, ui ) {} );

Example:

A simple jQuery UI Tabs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
 
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>tabs demo</title>
  <link rel="stylesheet" href="//code.jquery.com/ui/1.11.4/themes/smoothness/jquery-ui.css">
  <script src="//code.jquery.com/jquery-1.10.2.js"></script>
  <script src="//code.jquery.com/ui/1.11.4/jquery-ui.js"></script>
</head>
<body>
 
<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>$( "#tabs" ).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>
 
<script>
$( "#tabs" ).tabs();
</script>
 
</body>
</html>

Demo: