https://github.com/github/tab-container-element

An accessible tab container element with keyboard support.
https://github.com/github/tab-container-element

custom-elements web-components

Last synced: 4 months ago
JSON representation

An accessible tab container element with keyboard support.

• Host: GitHub
• URL: https://github.com/github/tab-container-element
• Owner: github
• License: mit
• Created: 2018-12-12T10:38:21.000Z (over 5 years ago)
• Default Branch: main
• Last Pushed: 2024-03-08T15:06:38.000Z (4 months ago)
• Last Synced: 2024-03-09T16:08:26.181Z (4 months ago)
• Topics: custom-elements, web-components
• Language: JavaScript
• Homepage: https://github.github.com/tab-container-element/examples/
• Size: 1.03 MB
• Stars: 336
• Watchers: 189
• Forks: 36
• Open Issues: 1
• Metadata Files:
  • Readme: README.md
  • License: LICENSE
  • Codeowners: CODEOWNERS

Lists

• awesome-standalones - `<tab-container>`
• awesome-stars - tab-container-element

README

        
# <tab-container> element

A accessible tab container element with keyboard support. Follows the [ARIA best practices guide on tabs](https://www.w3.org/WAI/ARIA/apg/patterns/tabpanel/).

## Installation

```

$ npm install @github/tab-container-element

```

## Usage

```js

import '@github/tab-container-element'

```

```html

  Tab one

  Tab two

  Tab three

  


    Panel 1

  

  


    Panel 2

  

  


    Panel 3

  


```

If none of the tabs have `aria-selected=true`, then the first tab will be selected automatically. You can also add the `default-tab=N` attribute to avoid having to set `aria-selected=true` on the desired tab, where `N` is the 0-based tab index:

```html

  Tab one

  Tab two

  Tab three

  

### Events

- `tab-container-change` (bubbles, cancelable): fired on `` before a new tab is selected and visibility is updated. `event.tab` is the tab that will be focused and `tab.panel` is the panel that will be shown if the event isn't cancelled.

- `tab-container-changed` (bubbles): fired on `` 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) and `event.panel` is the newly visible tab panel.

### Parts

- `::part(tablist-wrapper)` is the wrapper which contains `before-tabs`, `tablist` and `after-tabs`.

- `::part(tablist)` is the container which wraps all tabs. This element appears in ATs as it is `role=tablist`.

- `::part(panel)` is the container housing the currently active tabpanel.

- `::part(before-tabs)` is the container housing any elements that appear before the first `role=tab`. This also can be directly slotted with `slot=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 last `role=tab`. This also can be directly slotted with `slot=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 last `role=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 tab panel contents are controls

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, apply `data-tab-container-no-tabstop` to the `tabpanel` element.

```html

  Tab one

  Tab two

  


    


      
branch-one

      
branch-two

    

  

  


    


      
Commit One

      
Commit Two

    

  


```

### Vertical tabs

If `` is given the `vertical` attribute it will apply the `aria-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, apply `data-tab-container-no-tabstop` to the `tabpanel` element.

```html

  Tab one

  Tab two

  


    


      
branch-one

      
branch-two

    

  

  


    


      
Commit One

      
Commit Two

    

  


```

## Browser support

Browsers without native [custom element support][support] require a [polyfill][].

- Chrome

- Firefox

- Safari

- Microsoft Edge

[support]: https://caniuse.com/#feat=custom-elementsv1

[polyfill]: https://github.com/webcomponents/polyfills/tree/master/packages/custom-elements

## Development

```

npm install

npm test

```

## License

Distributed under the MIT license. See LICENSE for details.