Skip to content
Tabs component for dividing content into meaningful sections
JavaScript CSS
Branch: master
Clone or download
chee Revert "pin occ to version"
This reverts commit b6149b2.
Latest commit b506b0d Sep 19, 2019

README.md

o-tabs Build Status MIT licensed

Tabs component for dividing content into meaningful sections.

Usage

Markup

The tablist, tabs and tabpanels must be identified by ARIA role attributes.

The tab elements must contain a link whose href attribute points to the ID of a tabpanel element.

The tabpanel elements must have a o-tabs__tabpanel class added to them.

This is an example of an HTML structure that o-tabs will accept:

<ul data-o-component="o-tabs" class="o-tabs" role="tablist">
	<li role="tab"><a href="#tabContent1">Tab 1</a></li>
	<li role="tab"><a href="#tabContent2">Tab 2</a></li>
	<li role="tab"><a href="#tabContent3">Tab 3</a></li>
</ul>
<div id="tabContent1" class="o-tabs__tabpanel">
	Tab content 1
</div>
<div id="tabContent2" class="o-tabs__tabpanel">
	Tab content 2
</div>
<div id="tabContent3" class="o-tabs__tabpanel">
	<div>Note: first elements of each tab will get focused when it is selected. In this case, this div will receive focus.</div>
	Tab content 3
</div>

To set the initially selected tab, add an aria-selected="true" attribute to a tab element, otherwise the first tab will be selected automatically.

Config

You can set config options declaratively by using [data-o-tabs-] prefixed data attributes.

Options consist of:

  • data-o-tabs-disablefocus="true" - prevent the tabpanel being focused when selected.
  • data-o-tabs-update-url="true" - update the URL with the # of the selected panel.

Core experience

Without the accompanying JavaScript, the tabs will receive no styling, and all tabpanels will remain visible. It's recommended that the default styling is to have each of the tabpanels displayed one below the other.

A product may choose to hide the tabs like this:

.o-tabs { display: none; }
.o-tabs--js { display: block; }

ARIA

ARIA attributes will be set on elements as follows:

On init, aria-controls is added to each tab element, with value being the ID of the associated tabpanel.

On init and selected tab change these attributes are set and updated as appropriate:

  • aria-selected is set on the tab elements
  • aria-hidden and aria-expanded are set on the tabpanels

These state attributes are used by the o-tabs CSS.

JavaScript

Declarative

A o.DOMContentLoaded event can be dispatched on the document to auto-construct a o-tabs object for each element with a data-o-component="o-tabs" attribute:

document.addEventListener("DOMContentLoaded", function() {
	document.dispatchEvent(new CustomEvent('o.DOMContentLoaded'));
});

Auto-construction can be disabled for a specific element via another data attribute (data-o-tabs-autoconstruct="false").

Note that for browsers that do not support DOMContentLoaded (IE8 etc), the event could be polyfilled, or construction can be manually invoked:

const Tabs = require('o-tabs');
const tabsObjects = Tabs.init(document.body, {
	disablefocus: false
});

An array of any constructed Tabs objects will be returned.

Tabs.init(config) will not create Tabs objects for elements that already have Tabs objects constructed on them, therefore it's safe to call more than once on the same page region.

Imperative

const Tabs = require('o-tabs');
const myTabs = new Tabs(document.getElementById('myTabsRootElement'), {
	disablefocus: false
});

Events

The following events will be dispatched on the Tabs' root DOM element:

  • oTabs.ready: The Tabs object has initialised. Event detail:
    • tabs: The o-tabs object.
  • oTabs.tabSelect: A tab has been selected. Event detail:
    • tabs: The o-tabs object.
    • selected: The index of the selected tab.
    • lastSelected: The index of the last selected tab.

API

Tabs are indexed starting from 0.

The following API methods are provided:

  • init(config): Set attributes/classes, bind events. Called automatically on construction. Does nothing if already been called. config object accepts:
    • disablefocus: If set to true, it will stop the aria-selected tab from receiving focus.
  • selectTab(idx): Select tab idx. Does nothing if tab idx does not exist or is already selected.
  • destroy(): Unbind events, remove o-tabs--js class. After calling this, init() can be called again to re-initialise the tabs.

Sass

o-tabs comes with either base styling, which should be used as a base for you to add your own styling. Or full styling called buttontabs; based on the buttons from o-buttons).

To apply the buttontabs styling, add a o-tabs--buttontabs class to the root element:

<ul data-o-component="o-tabs" class="o-tabs o-tabs--buttontabs" role="tablist">

or use the mixin:

@include oTabsButtonTabs;

The buttontabs style comes in two sizes that conform to the o-buttons sizes: medium and big. Medium is the default size and big can be applied by adding the class o-tabs--big.

Options

  • Align right: Add o-tabs--alignright to the root element.

Mixins

o-tabs styles are also available via mixins. The base styles and buttontabs styles are available using the oTabs and oTabsButtonTabs mixins.

If you're using the Sass mixins, you can also theme o-tabs using the oTabsButtonTabsTheme mixin, which can be set to any of the o-buttons themes by passing the name as a parameter:

@include oTabsButtonTabsTheme($theme: 'inverse', $selector: false);

Custom themes are also supported using oTabsButtonTabsTheme and the same custom theme map as for o-buttons custom themes.

Migration Guide

Migrating from v3 to v4

This major includes the new o-colors and o-buttons, and updates the themes and sizes of button tabs.

The following changes have been made to the themes:

  • Standout is now Primary: use oTabsButtonTabsTheme('primary')
  • Uncolored is now Mono: use oTabsButtonTabsTheme('mono')

As well as this, the JavaScript for o-tabs now relies on String.prototype.trim. This is present in modern browsers and can be polyfilled in others.


Contact

If you have any questions or comments about this component, or need help using it, please either raise an issue, visit #ft-origami or email Origami Support.


Licence

This software is published by the Financial Times under the MIT licence.

You can’t perform that action at this time.