The tab-list Elements

The tab-list, tab-item, and tab-panel elements together represent content that is presented one panel at a time. They are built with accessibility in mind and implement the WAI-ARIA guidelines for tabs.

• A tab-list represents a set of tabs, where only one tab's contents may be presented at a time.
• A tab-item represents a reference of a single panel of information in a tab list.
• A tab-panel represents a panel of information.

<tab-list aria-label="Learn about fruits">
    <tab-item for="example-1-tab-1" selected>Apples</tab-item>
    <tab-item for="example-1-tab-2">Oranges</tab-item>
    <tab-item for="example-1-tab-3">Bananas</tab-item>
</tab-list>
<tab-panel id="example-1-tab-1">
    <p>Apples are usually red, but sometimes they can be green.</p>
</tab-panel>
<tab-panel id="example-1-tab-2">
    <p>Oranges are, well, orange!</p>
</tab-panel>
<tab-panel id="example-1-tab-3">
    <p>Bananas are yellow and usually curved.</p>
</tab-panel>

Installation

You can import through CDN:

<script type="module" src="https://unpkg.com/@auroratide/tab-list/lib/define.js"></script>

Or, you may install through NPM and include it as part of your build process:

$ npm i @auroratide/tab-list

import '@auroratide/tab-list/lib/define.js'

Usage

tab-list, tab-item, and tab-panel are markup elements that you can use in your HTML document. To use them together, it is best to follow these guidelines:

• tab-item elements must be contained within a tab-list. They need not be direct descendents.
• tab-panel must define a unique id.
• tab-item must define the for attribute, whose value is the id of its corresponding tab-panel.

<tab-list>
    <!-- tab-item must be in a tab-list, and defines `for` to be
         the corresponding tab-panel id -->
    <tab-item for="tab-panel-id">
</tab-list>
<!-- tab-panel defines an id -->
<tab-panel id="tab-panel-id">
    <p>Any content you want</p>
</tab-panel>

The following are good accessibility practices:

• tab-list should be labelled with a name representing the collection of tabs, either with aria-label or aria-labelledby.
• tab-panel elements can theoretically be anywhere on the page, though it's best if they are the next focusable item after the tab-list.

Automatic Activation

By default, a tab must be clicked in order for its panel to be revealed. With automatic activation, a tab only needs to acquire focus to show its tab. In general, WAI-ARIA recommends automatic activation for the best accessibility, unless animations induce lag.

You can enable automatic activation by setting the activation attribute to "automatic" on the tab list element.

<tab-list activation="automatic" aria-label="Learn about vegetables">
    <tab-item for="example-5-tab-1" selected>Tomatoes</tab-item>
    <tab-item for="example-5-tab-2">Carrots</tab-item>
    <tab-item for="example-5-tab-3">Squashes</tab-item>
</tab-list>

Vertical Tab List

By default, tabs are listed horizontally, and they can be navigated with the left and right arrow keys.

By setting the orientation attribute to "vertical", you can make a vertical tab list. This makes it navigable with the up and down arrow keys instead.

<tab-list orientation="vertical" aria-label="Learn about vegetables">
    <tab-item for="example-2-tab-1" selected>Tomatoes</tab-item>
    <tab-item for="example-2-tab-2">Carrots</tab-item>
    <tab-item for="example-2-tab-3">Squashes</tab-item>
</tab-list>

Setting a selected tab

You can set the selected attribute on one tab-item in a tab-list. This will mark that item as selected and show its panel.

<tab-item selected for="example-3-tab-3">Bananas</tab-item>

Note: Only one tab-item can be selected at a time! If you attempt to set multiple as selected, only the first selected tabl's panel will be shown.

All Attributes

For tab-list:

| Attribute | Description | | ------------- | ------------- | | orientation | Either "horizontal" or "vertical". Represents whether the tab list should be presented horizontally or vertically, and affects whether they are navigated with the left/right or up/down keys respectively. "horizontal" by default. | | activation | Either "manual" or "automatic". Represents whether a click (manual) or focus (automatic) is required to show a tab's panel. "manual" by default. |

For tab-item:

| Attribute | Description | | ------------- | ------------- | | for | Required. Should be the same as the id of the tab's respective panel. | selected | Either present or not. Represents whether this tab's panel should be shown. |

CSS Customization

Since these are native custom elements, they can be styled the same way as regular HTML elements.

Of note:

• tab-item[selected] will style the currently selected tab.
• tab-list[orientation="vertical"] can style vertical tab lists.
• tab-panel[hidden] styles hidden tabs, in case you want transitions.

Here's an example of a fully customized tab list:

div.tab-container {
    box-shadow: 0 2px 4px hsla(0, 0%, 0%, 0.25);
}

tab-list {
    background: hsl(210, 68%, 45%);
    gap: 0;
}

tab-item {
    border: none;
    border-radius: 0;
    background: hsl(210, 68%, 45%);
    color: hsl(0, 0%, 100%);
    padding: 12px 24px;
    border-right: 2px solid hsl(210, 82%, 25%);
}

tab-item:hover:not([selected]),
tab-item:focus:not([selected]) {
    background: hsl(210, 82%, 25%);
}

tab-item[selected] {
    background: hsl(0, 0%, 100%);
    border-color: transparent;
    color: hsl(0, 0%, 0%);
}

div.tab-panels-container { display: grid; }
tab-panel {
    grid-area: 1 / 1;
    border: none;
    padding: 12px 24px 24px;
    opacity: 1;
    transition: opacity 0.2s ease-in-out;
}

tab-panel[hidden] {
    display: block;
    opacity: 0;
}

Events

The tab-list element dispatches the following events:

| Name | When Triggered | | ------------- | ------------- | | tab-list:change | Whenever the currently selected tab changes |

The tab-list:change event contains references to the previously selected tab and the newly selected tab:

tabList.addEventListener('tab-list:change', e => {
    console.log(e.detail.from)
    console.log(e.detail.to)
})

Accessibility

This custom element is built with accessibility in mind! It follows the WAI-ARIA guidelines for tabs (the tablist, tab, and tabpanel roles).

• When focus enters the tab list, the currently active tab item is focused.
• Left and Right can be used to navigate the tabs.
• Enter or Space select the currently focused tab.
• Home goes to the first tab, and End goes to the last tab.

Not (yet) Implemented

The following features are desired of tab lists, but are not yet implemented:

• Auto-opening a panel when its corresponding tab receives focus.
• Native support for removable tabs.
• Tabs that open popup menus.