Dependency-free plain JavaScript module for WCAG compliant tablists
npm install aria-tablist
Dependency-free plain JavaScript module for WCAG compliant tablists. Also great for accordions.
Key design goals and features are:
- multi and single select modes
- horizontal and vertical modes: Adjusts arrow key usage for moving focus between tabs
- progressive enhancement: Allows for only the tab and panel relationship to be indicated in the DOM, and adds role and aria attributes automatically as needed
- accessibility: Follows the WCAG spec by default, with options to tweak behaviour
- compatibility: Broad browser and device support (IE9+)
- starting states: Can use aria-selected="true" or data-selected="true" to indicate which tab(s) should be enabled by default.
- deletion: Can enable tab (and panel) deletion using the delete key
Grab from NPM and use in a module system:
``
npm install aria-tablist
`javascript`
import AriaTablist from 'aria-tablist';
AriaTablist(document.getElementById('tablist'), options);
Or grab the minified JavaScript from unpkg:
`html`
The module relies entirely on standard attributes: it sets the role on elements if it needs to, aria- attributes for indicating behaviour to screen readers, and relies on setting and removing hidden="hidden" to toggle element visibility. This means that you can use all of your own class names and styling, and the module won't override them.
When the module is called on an element, the following steps are taken:
1. The module will search for tab elements using the tabSelector option ('[role="tab"]' by default).tab
2. If none are found, all direct children will be processed.
3. For each assumed , the module will check for a matching tabpanel by:aria-controls
1. Checking for an or data-controls attribute on the tab, and searching for an element with a matching id.tab
2. If the has an id, searching for an element with an aria-labelledby or data-labelledby attribute that matches that id.role="tab"
4. For any tabs that were processed where a matching panel was not found, if they had set, the role attribute will be removed to prevent confusion to screen reader users.role
5. The found tabs and associated panels will then have the relevant and aria- attributes set automatically.
This means your HTML only needs to indicate the relationship between the tabs and panels, and the module will handle the rest:
`html
Panel 1
Panel 2
Panel 3
`
So if you need to cater for users without JavaScript, or if the JavaScript fails to load for whatever reason, there won't be any applicable roles set that would confuse a screen reader user.
You can of course include all of the optimal ARIA attributes straight away if you wish, including indicating which tab should be active by default:
`html
Apple
Orange
Pear
Options
Most of the functionality is assumed from the included ARIA attributes in your HTML (see the examples). The remaining available options and their defaults are:
typescript
{
/**
* delay in milliseconds before showing tab(s) from user interaction
*/
delay: number = 0; /**
* allow tab deletion via the keyboard - can be overridden per tab by setting
data-deletable="false"
*/
deletable: boolean = false; /**
* make all tabs focusable in the page's tabbing order (by setting a
on them), instead of just 1
*/
focusableTabs: boolean = false; /**
* make all tab panels focusable in the page's tabbing order (by setting a
tabindex on them)
*/
focusablePanels: boolean = true; /**
* activate a tab when it receives focus from using the arrow keys
*/
arrowActivation: boolean = false;
/**
* enable all arrow keys for moving focus, instead of horizontal or vertical arrows based on
aria-orientation attribute
* (left and up for previous, right and down for next)
*/
allArrows: boolean = false; /**
* the selector to use when initially searching for tab elements;
* if none are found, all direct children of the main element will be processed
*/
tabSelector: string = '[role="tab"]';
/**
* value to use when setting tabs or panels to be part of the page's tabbing order
*/
tabindex: number | string = 0;
/**
* callback each time a tab opens
*/
onOpen: (panel: HTMLElement, tab: HTMLElement) => void;
/**
* callback each time a tab closes
*/
onClose: (panel: HTMLElement, tab: HTMLElement) => void;
/**
* callback when a tab is deleted
*/
onDelete: (tab: HTMLElement) => void;
/**
* callback once ready
*/
onReady: (tablist: HTMLElement) => void;
}
`All component options that accept a Function will have their context (
) set to include the full autocomplete API (assuming you use a normal function: () {} declaration for the callbacks instead of arrow functions).API
The returned
AriaTablist class instance exposes the following API (which is also available on the original element's ariaTablist property):`typescript
{
/**
* the tab elements the module currently recognises
*/
tabs: HTMLElement[]; /**
* the panel elements the module currently recognises
*/
panels: HTMLElement[];
/**
* the current options object
*/
options: AriaTablistOptions;
/**
* trigger a particular tab to open (even if disabled)
*/
open(index: number | HTMLElement, focusTab: boolean = true): void;
/**
* trigger a particular tab to close (even if disabled)
*/
close(index: number | HTMLElement, focusTab: boolean = false): void;
/**
* delete a particular tab and its corresponding panel (if deletable)
*/
delete(index: number | HTMLElement): void;
/**
* destroy the module - does not remove the elements from the DOM
*/
destroy(): void;
}
``