Repository files navigation

A accessible tab container element with keyboard support. Follows theARIA best practices guide on tabs.

$ npm install @github/tab-container-element

import'@github/tab-container-element'

<tab-container><buttontype="button"id="tab-one"role="tab"aria-selected="true">Tab one</button><buttontype="button"id="tab-two"role="tab"tabindex="-1">Tab two</button><buttontype="button"id="tab-three"role="tab"tabindex="-1">Tab three</button><divrole="tabpanel"aria-labelledby="tab-one">    Panel 1</div><divrole="tabpanel"aria-labelledby="tab-two"hidden>    Panel 2</div><divrole="tabpanel"aria-labelledby="tab-three"hidden>    Panel 3</div></tab-container>

If none of the tabs havearia-selected=true, then the first tab will be selected automatically. You can also add thedefault-tab=N attribute to avoid having to setaria-selected=true on the desired tab, whereN is the 0-based tab index:

<!-- The _second_ tab will be selected --><tab-containerdefault-tab="1"><buttontype="button"id="tab-one"role="tab">Tab one</button><buttontype="button"id="tab-two"role="tab">Tab two</button><buttontype="button"id="tab-three"role="tab">Tab three</button><!-- ... --></tab-container>

• tab-container-change (bubbles, cancelable): fired on<tab-container> before a new tab is selected and visibility is updated.event.tab is the tab that will be focused,event.tabIndex is the 0-based index of thetab andtab.panel is the panel that will be shown if the event isn't cancelled.
• tab-container-changed (bubbles): fired on<tab-container> after a new tab is selected and visibility is updated.event.tab is the tab that is now active (and will be focused right after this event),event.tabIndex is the 0-based index of thetab andevent.panel is the newly visible tab panel.

• ::part(tablist-wrapper) is the wrapper which containsbefore-tabs,tablist andafter-tabs.
• ::part(tablist) is the container which wraps all tabs. This element appears in ATs as it isrole=tablist.
• ::part(panel) is the container housing the currently active tabpanel.
• ::part(before-tabs) is the container housing any elements that appear before the firstrole=tab. This also can be directly slotted withslot=before-tabs. This container lives outside the element with role=tablist to adhere to ARIA guidelines.
• ::part(after-tabs) is the container housing any elements that appear after the lastrole=tab. This also can be directly slotted withslot=after-tabs. This container lives outside the element with role=tablist to adhere to ARIA guidelines.
• ::part(after-panels) is the container housing any elements that appear after the lastrole=tabpanel. This can be useful if you want to add a visual treatment to the container but have content always appear visually below the active panel.

When activated, the whole tab panel will receive focus. This may be undesirable, in the case where the tab panel is itself composed of interactive elements, such as an action list or radio buttons.

In those cases, applydata-tab-container-no-tabstop to thetabpanel element.

<tab-container><buttontype="button"id="tab-one"role="tab"aria-selected="true">Tab one</button><buttontype="button"id="tab-two"role="tab"tabindex="-1">Tab two</button><divrole="tabpanel"aria-labelledby="tab-one"data-tab-container-no-tabstop><ulrole="menu"aria-label="Branches"><litabindex="0">branch-one</li><litabindex="0">branch-two</li></ul></div><divrole="tabpanel"aria-labelledby="tab-two"data-tab-container-no-tabstophidden><ulrole="menu"aria-label="Commits"><litabindex="0">Commit One</li><litabindex="0">Commit Two</li></ul></div></tab-container>

If<tab-container> is given thevertical attribute it will apply thearia-orientation=vertical attribute to the tablist. This will present to ATs as a vertical tablist, and you can use the attribute to style the tabs accordingly.

In those cases, applydata-tab-container-no-tabstop to thetabpanel element.

<tab-containervertical><buttontype="button"id="tab-one"role="tab"aria-selected="true">Tab one</button><buttontype="button"id="tab-two"role="tab"tabindex="-1">Tab two</button><divrole="tabpanel"aria-labelledby="tab-one"data-tab-container-no-tabstop><ulrole="menu"aria-label="Branches"><litabindex="0">branch-one</li><litabindex="0">branch-two</li></ul></div><divrole="tabpanel"aria-labelledby="tab-two"data-tab-container-no-tabstophidden><ulrole="menu"aria-label="Commits"><litabindex="0">Commit One</li><litabindex="0">Commit Two</li></ul></div></tab-container>

<tab-container> aims to simplify complex markup away in the ShadowDOM, so that the HTML you end up writing is overall less. However sometimes it can be useful to havefull control over the markup. Each of the::part selectors are also<slot>s, this means you can take any part and slot it, overriding the built-in ShadowDOM.

You are able to provide your ownrole=tablist and<tab-container> will accommodate. This can be useful if you need extra presentational markup in the tablist. But remember:

• You must ensure that all child elements arerole=tab orrole=presentational.
• The element will still slot contents before and after this element, in order to correctly present the tablist.

<tab-container><divrole="tablist"><my-iconname="tabs"role="presentational"></my-icon><buttontype="button"role="tab">Tab one</button><buttontype="button"role="tab">Tab two</button></div><divrole="tabpanel"></div><divrole="tabpanel"></div></tab-container>

You are able to slot thetablist-tab-wrapper part. This slot manages the tabs but not the before or after elements. In this way, you can put custom HTML inside the tab list. Bear in mind if you're supplying this element that:

• You must also supply arole=tablist as a child.
• You must ensure that all child elements arerole=tab orrole=presentational.
• The element will still slot contents before and after this element, in order to correctly present the tablist.

<tab-container><divslot="tablist-tab-wrapper"><divrole="tablist"><buttontype="button"role="tab">Tab one</button><buttontype="button"role="tab">Tab two</button></div></div><divrole="tabpanel"></div><divrole="tabpanel"></div></tab-container>

If you want to take full control over the entire tab region, including managing the content before and after the tabs, then you can slot thetablist-wrapper element. Bear in mind if you're supplying this element that:

• <tab-container> will only manage slotting ofrole=panel. It won't manage elements before or after the tabs or panels.
• You won't be able to also slot thetablist-tab-wrapper. You can chose to omit this element though.
• You must also supply arole=tablist as a descendant.
• You must ensure that all child elements of the tablistrole=tab orrole=presentational.
• The element will still slot contents before and after this element, in order to correctly present the tablist.

<tab-container><divslot="tablist-wrapper"><divrole="tablist"><buttontype="button"role="tab">Tab one</button><buttontype="button"role="tab">Tab two</button></div></div><divrole="tabpanel"></div><divrole="tabpanel"></div></tab-container>

Browsers without nativecustom element support require apolyfill.

• Chrome
• Firefox
• Safari
• Microsoft Edge

npm installnpm test

Distributed under the MIT license. See LICENSE for details.