Tabbed Interface Web Component

A web component that transforms heading-structured content into an accessible tabbed interface. This is a modern web component port of Aaron Gustafson's original TabInterface.

Demo

• Live Demo (Source)
• unpkg Demo (Source)
• esm.sh Demo (Source)

Features

• Progressive Enhancement: Works with semantic HTML structure
• Accessibility: Full ARIA support and keyboard navigation
• Customizable: Extensive CSS custom properties for styling
• Lightweight: No dependencies, pure vanilla JavaScript
• Modern: Uses Shadow DOM and ES Modules
• TypeScript-ready: Ships bundled type definitions for editors and build tooling

TypeScript & Framework Support

• Bundled .d.ts files describe both TabbedInterfaceElement and defineTabbedInterface, so editors, bundlers, and framework toolchains get type information automatically.
• The showHeaders, tablistAfter, autoActivate, and defaultTab properties reflect to attributes, keeping declarative markup and imperative code in sync.
• A private upgradeProperty helper replays any property assignments that happen before the browser upgrades the element, which is especially helpful for SSR and hydration workflows.
• The defaultTab property accepts either zero-based indices or heading IDs, making it easy to drive tab selection from reactive state or router parameters.

Installation

npm install @aarongustafson/tabbed-interface

Usage

Basic Usage

<tabbed-interface>
  <h2>First Tab</h2>
  <p>Content for the first tab panel.</p>

  <h2>Second Tab</h2>
  <p>Content for the second tab panel.</p>

  <h2>Third Tab</h2>
  <p>Content for the third tab panel.</p>
</tabbed-interface>

<script type="module">
  import '@aarongustafson/tabbed-interface/define.js';
</script>

Import Options

Auto-define (browser environments only):

import '@aarongustafson/tabbed-interface/define.js';
// Registers <tabbed-interface> when customElements is available

Prefer to control when registration happens? Call the helper directly:

import { defineTabbedInterface } from '@aarongustafson/tabbed-interface/define.js';

defineTabbedInterface();

Manual registration:

import { TabbedInterfaceElement } from '@aarongustafson/tabbed-interface';
customElements.define('my-tabs', TabbedInterfaceElement);

Attributes

Examples

<!-- Show headings in panels -->
<tabbed-interface show-headers>
  ...
</tabbed-interface>

<!-- Tabs after content -->
<tabbed-interface tablist-after>
  ...
</tabbed-interface>

<!-- Start on specific tab -->
<tabbed-interface default-tab="2">
  ...
</tabbed-interface>

<!-- Start on tab by heading ID -->
<tabbed-interface default-tab="features">
  <h2 id="intro">Introduction</h2>
  <p>...</p>
  <h2 id="features">Features</h2>
  <p>...</p>
</tabbed-interface>

<!-- Auto-activation (tabs activate on focus) -->
<tabbed-interface auto-activate>
  ...
</tabbed-interface>

Properties

Methods

Programmatic Control

const $tabs = document.querySelector('tabbed-interface');

// Navigate
$tabs.next();
$tabs.previous();
$tabs.first();
$tabs.last();

// Set active tab directly
$tabs.activeIndex = 2;

Events

document.querySelector('tabbed-interface')
  .addEventListener('tabbed-interface:change', (e) => {
    console.log(`Switched to tab ${e.detail.tabIndex}`);
  });

Keyboard Navigation

Styling with CSS Parts

Style the component's shadow DOM elements using CSS ::part() selectors:

Available Parts

Styling Examples

Basic styling:

tabbed-interface::part(tablist) {
  gap: 4px;
  background: #f0f0f0;
  padding: 8px;
}

tabbed-interface::part(tab) {
  padding: 0.75em 1.5em;
  background: white;
  border: 1px solid #ccc;
  border-radius: 4px 4px 0 0;
  font-weight: 500;
}

tabbed-interface::part(tab):hover {
  background: #e9e9e9;
}

tabbed-interface::part(tabpanel) {
  padding: 2em;
  border: 1px solid #ccc;
  background: white;
}

Targeting specific states:

/* Active tab - use attribute selector on the host */
tabbed-interface::part(tab selected) {
  background: white;
  border-bottom-color: white;
  font-weight: bold;
}

/* Focus styles */
tabbed-interface::part(tab):focus-visible {
  outline: 3px solid blue;
  outline-offset: 2px;
}

Themed variations:

/* Pills style */
.pills::part(tablist) {
  gap: 8px;
  background: transparent;
}

.pills::part(tab) {
  border-radius: 20px;
  background: #e0e0e0;
}

.pills::part(tab)[aria-selected="true"] {
  background: #007bff;
  color: white;
}

/* Minimal style */
.minimal::part(tab) {
  border: none;
  border-bottom: 2px solid transparent;
  border-radius: 0;
  background: transparent;
}

.minimal::part(tab)[aria-selected="true"] {
  border-bottom-color: #007bff;
}

.minimal::part(tabpanel) {
  border: none;
  padding-top: 1.5em;
}

Custom Tab Titles

Use data-tab-short-name to show a different label in the tab than the heading. The full heading text is set as the aria-label for screen readers:

<tabbed-interface>
  <h2 data-tab-short-name="Intro">Introduction and Getting Started Guide</h2>
  <p>Full content with the complete heading visible in the panel.</p>
</tabbed-interface>

Hash Navigation

The component supports URL hash navigation. Link to specific tabs:

<a href="#features">Go to Features</a>

<tabbed-interface>
  <h2 id="intro">Introduction</h2>
  <p>...</p>
  <h2 id="features">Features</h2>
  <p>...</p>
</tabbed-interface>

Browser Support

Works in all modern browsers supporting:

• Custom Elements v1
• Shadow DOM v1
• ES Modules

Development

# Install dependencies
npm install

# Run tests
npm test

# Run tests once
npm run test:run

# Lint
npm run lint

# Format code
npm run format

License

MIT - See LICENSE

Credits

Based on the jQuery TabInterface plugin by Aaron Gustafson, which is itself a port of his original TabInterface.