Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
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 days 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 (about 6 years ago)
- Default Branch: main
- Last Pushed: 2024-09-27T10:19:25.000Z (4 months ago)
- Last Synced: 2025-01-16T05:04:57.023Z (11 days ago)
- Topics: custom-elements, web-components
- Language: JavaScript
- Homepage: https://github.github.com/tab-container-element/examples/
- Size: 1.05 MB
- Stars: 356
- Watchers: 231
- Forks: 26
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: CODEOWNERS
Awesome Lists containing this project
- awesome-standalones - `<tab-container>`
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, `event.tabIndex` is the 0-based index of the `tab` 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), `event.tabIndex` is the 0-based index of the `tab` 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
```
### Unmanaged slots
`` 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 have _full_ control over the markup. Each of the `::part` selectors are also ``s, this means you can take any part and slot it, overriding the built-in ShadowDOM.
#### Unmanaged `tablist`
You are able to provide your own `role=tablist` and `` will accommodate. This can be useful if you need extra presentational markup in the tablist. But remember:
- You must ensure that all child elements are `role=tab` or `role=presentational`.
- The element will still slot contents before and after this element, in order to correctly present the tablist.
```html
Tab one
Tab two
```
#### Unmanaged `tablist-tab-wrapper`
You are able to slot the `tablist-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 a `role=tablist` as a child.
- You must ensure that all child elements are `role=tab` or `role=presentational`.
- The element will still slot contents before and after this element, in order to correctly present the tablist.
```html
Tab one
Tab two
```
#### Unmanaged `tablist-wrapper`
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 the `tablist-wrapper` element. Bear in mind if you're supplying this element that:
- `` will only manage slotting of `role=panel`. It won't manage elements before or after the tabs or panels.
- You won't be able to also slot the `tablist-tab-wrapper`. You can chose to omit this element though.
- You must also supply a `role=tablist` as a descendant.
- You must ensure that all child elements of the tablist `role=tab` or `role=presentational`.
- The element will still slot contents before and after this element, in order to correctly present the tablist.
```html
Tab one
Tab 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.