@github/tab-container-element

中文文档
4.9.0发布于 2026/08/04MITTypeScriptES Module零依赖构建来源已验证近 30 天下载 23.2万

Tab container element

原始使用文档
文档目录11 节
  1. Installation
  2. Usage
  3. Events
  4. Methods
  5. Parts
  6. When tab panel contents are controls
  7. Vertical tabs
  8. Unmanaged slots
  9. Browser support
  10. Development
  11. License

<tab-container> element

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

Installation

$ npm install @github/tab-container-element

Usage

import '@github/tab-container-element'
<tab-container>
  <button type="button" id="tab-one" role="tab" aria-selected="true">Tab one</button>
  <button type="button" id="tab-two" role="tab" tabindex="-1">Tab two</button>
  <button type="button" id="tab-three" role="tab" tabindex="-1">Tab three</button>
  <div role="tabpanel" aria-labelledby="tab-one">
    Panel 1
  </div>
  <div role="tabpanel" aria-labelledby="tab-two" hidden>
    Panel 2
  </div>
  <div role="tabpanel" aria-labelledby="tab-three" hidden>
    Panel 3
  </div>
</tab-container>

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:

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

Events

  • 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 the tab and tab.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 the tab and event.panel is the newly visible tab panel.

Methods

  • selectTab(tabIndex, options: {focus?: boolean} = {}): programmatically selects the tab with the given 0-based index and shows its panel. Fires events as described above. By default, sets focus to the selected tab; call with {focus: false} to prevent this.

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.

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

Vertical tabs

If <tab-container> 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.

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

Unmanaged slots

<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 have full 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.

Unmanaged tablist

You are able to provide your own role=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 are role=tab or role=presentational.
  • The element will still slot contents before and after this element, in order to correctly present the tablist.
<tab-container>
  <div role="tablist">
      <my-icon name="tabs" role="presentational"></my-icon>
      <button type="button" role="tab">Tab one</button>
      <button type="button" role="tab">Tab two</button>
  </div>
  <div role="tabpanel"></div>
  <div role="tabpanel"></div>
</tab-container>

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.
<tab-container>
  <div slot="tablist-tab-wrapper">
    <div role="tablist">
        <button type="button" role="tab">Tab one</button>
        <button type="button" role="tab">Tab two</button>
    </div>
  </div>
  <div role="tabpanel"></div>
  <div role="tabpanel"></div>
</tab-container>

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:

  • <tab-container> 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.
<tab-container>
  <div slot="tablist-wrapper">
    <div role="tablist">
        <button type="button" role="tab">Tab one</button>
        <button type="button" role="tab">Tab two</button>
    </div>
  </div>
  <div role="tabpanel"></div>
  <div role="tabpanel"></div>
</tab-container>

Browser support

Browsers without native custom element support require a polyfill.

  • Chrome
  • Firefox
  • Safari
  • Microsoft Edge

Development

npm install
npm test

License

Distributed under the MIT license. See LICENSE for details.

版本与发布记录

@github/tab-container-element 共发布 38 个版本,首次发布于 2018/12/12;过去 12 个月发布了 1 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
4.9.0latest2026/08/043 个月前
4.8.22024/06/212 年前
4.8.12024/06/202 年前
4.8.02024/05/092 年前
4.7.02024/04/242 年前
4.6.02024/04/232 年前

关于 @github/tab-container-element 的常见问题

@github/tab-container-element 是什么?

Tab container element

如何安装 @github/tab-container-element?

在项目目录运行 npm install @github/tab-container-element,或使用 pnpm add / yarn add / bun add。

@github/tab-container-element 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@github/tab-container-element 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@github/tab-container-element 可以商用吗?

@github/tab-container-element 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@github/tab-container-element 的下载量有多少?

根据 npm 官方下载统计,@github/tab-container-element 在 2026/10/17 – 2026/11/15 这 30 天内被下载 232,386 次,日均约 7,746 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@github/tab-container-element 还在维护吗?

最新版本 4.9.0 发布于 2026/08/04(3 个月前);至今共发布 38 个版本,其中过去 12 个月发布了 1 个;首次发布于 2018/12/12。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。