Top

Usage

The tab component is primarily used in the display of multiple sections of content, with only a single section open at any time, all toggled through a navigation of tabbed links.

The tabs that make up the component should be wrapped in a .tab-nav (with data-tab-nav) and structured with a ul list. The sections that associate to tabs should be created with .tab-section and data-tab-section. Both of which can be wrapped by a .tabs element.

<div class="tabs" data-tab>
    <nav class="tab-nav" data-tab-nav>
        <ul>
            <li><a href="#one">First</a></li>
            <li><a href="#two">Second</a></li>
            <li><a href="#three">Third</a></li>
        </ul>
    </nav>

    <section class="tab-section" data-tab-section>...</section>
    <section class="tab-section" data-tab-section>...</section>
    <section class="tab-section" data-tab-section>...</section>
</div>

The component should be initialized on an element that wraps both the navigation and the sections.

$('.tabs').tab();
The data-tab-* attributes are required so that the JavaScript layer can find or bind elements in the DOM.
Tabs can be nested by utilizing component namespaces.
The markup for tabs can be customized and re-arranged extensively. The only requirements are the inclusion of tab data attributes.
The href of every tab does not point to a section ID. For every tab, there needs to be an associated section in the markup, even if it's empty. The order and index in the collection determines association.

Horizontal Tabs

To display tabs horizontally alongside sections, and to update all navigation items to a vertical layout, use .tabs--horizontal. We suggest pairing this with the Grid component.

<div class="tabs tabs--horizontal grid">
    <nav class="tab-nav col span-4" data-tab-nav>
        <ul>
            <li><a href="#one">First</a></li>
            <li><a href="#two">Second</a></li>
            <li><a href="#three">Third</a></li>
        </ul>
    </nav>

    <div class="col span-8">
        <section class="tab-section" data-tab-section>...</section>
        <section class="tab-section" data-tab-section>...</section>
        <section class="tab-section" data-tab-section>...</section>
    </div>
</div>

Persist State

There are 2 ways to persist the open section between requests. The first, which also takes highest priority, is through cookies.

$('.tabs').tab({
    persistState: true,
    cookie: 'foobar'
});
When using cookies, a $.cookie() method needs to exist on the jQuery object.

The second is through the hash fragment in the URL. We can either update the hash manually when a tab is clicked, or disable preventDefault and set the href to IDs.

$('.tabs').tab({
    loadFragment: true,
    preventDefault: false
});

Lastly, if neither of those states are persisted, then the defaultIndex will be used.

AJAX Loading

Loading in sections through AJAX is extremely easy, simple set the href on the tabs with the URL we want to request via AJAX.

<div class="tabs">
    <nav class="tab-nav" data-tab-nav>
        <ul>
            <li><a href="/load/this">AJAX 1st</a></li>
            <li><a href="/load/that">AJAX 2nd</a></li>
            <li><a href="#three">Non-AJAX</a></li>
        </ul>
    </nav>

    <section class="tab-section" data-tab-section></section>
    <section class="tab-section" data-tab-section></section>
    <section class="tab-section" data-tab-section>...</section>
</div>
Be sure to create empty sections to insert the response into, as the component does not automatically create them!

Notes

  • The .show and .hide classes will be toggled on the .tab-section to trigger display.
  • The currently open section will have an .is-active class on the tabs parent li.
Top

ARIA

The tab, tablist, and tabpanel roles, and the appropriate aria-* attributes are required when supporting ARIA.

<div class="tabs">
    <nav class="tab-nav" role="tablist" data-tab-nav>
        <ul>
            <li><a href="#one" role="tab">First</a></li>
        </ul>
    </nav>

    <section class="tab-section" role="tabpanel" data-tab-section>...</section>
</div>
The JavaScript component will automatically map all ARIA attributes.
Top

Variables

Variable Default Description
$tab-class .tabs CSS class name for the tabs wrapper.
$tab-class-modifier-horizontal .tabs--horizontal CSS class name for the tabs horizontal modifier.
$tab-class-nav .tab-nav CSS class name for the tabs navigation wrapper.
$tab-class-section .tab-section CSS class name for the individual tab section.
$tab-modifiers ("horizontal") List of modifiers to include in the CSS output. Accepts horizontal.
Top

Options

Inherits all options from the parent Component.

Option Type Default Description
collapsible bool false Allows the open section to be closed, without having to open another section.
cookie string The name of the cookie when persistState is true.
cookieDuration int 30 The duration in days to store the cookie.
defaultIndex int 0 The index of the section to open on page load. Can be overridden by a fragment or cookie.
getUrl string url The HTML attribute on the tab to get the URL for AJAX requests.
loadFragment bool true Open the section that matches the current hash fragment.
mode string click The type of interaction for toggling a section. Accepts click or hover.
persistState bool false Persist the open tab between requests through cookies.
preventDefault bool true Prevent the default action on navigation tabs.
Top

Events

Inherits all events from the parent Component.

Event Arguments Description
load string:response Triggered when a section is loaded via AJAX.
showing int:oldIndex Triggered before the section is shown.
shown int:newIndex Triggered after the section is shown.
Top

Properties

Inherits all properties from the parent Component.

Property Type Description Found With
cache object Collection of cached AJAX requests indexed by URL.
index int The index of the currently opened section.
nav element The element containing the navigation links (the tabs). [data-tab-nav]
sections collection A collection of section elements within the tab wrapper. [data-tab-section]
tabs collection A collection of tab elements within the nav. [data-tab-nav] a
Top

Methods

Inherits all methods from the parent Component.

Method Description Bound To
jump(int:index) Open a specific section using the index in the collection.
show(element:tab) Open a specific section using the related tab element. [data-tab-nav] a