Tablist widgets (or: tab panels, tabs)

Tablists are used to divide complex page content into smaller, more manageable sections. Each section is represented by a tab label that allows users to display one panel at a time. In this sense, tablists can be understood as small, self-contained page fragments within a larger page.

Tablists are well known as native controls in many operating systems: a list of controls (usually on top of the element) allows to toggle the visibility of corresponding panels. Only a single control can be active at a time, so exactly one panel is visible and all others are hidden.

Tablist

We use the term tablist instead of simply tabs to avoid confusion with the Tab key used for keyboard navigation.

General requirements

The following requirements are based on established best practices and the WAI-ARIA Authoring Practices: Tab Panel Widget.

In particular, a compliant tablist must fulfil the following criteria:

The purpose and usage of the tablist must be clearly understandable.
The active and inactive states of tabs must be visually and programmatically perceivable.
Users must receive clear feedback when a tab is activated.
The tablist must be fully operable using:
- keyboard only,
- screen readers (desktop and mobile),
- standard interaction keys (Tab, Enter/Space, Home/End, arrow keys).
Panel content must be easily accessible via keyboard and assistive technologies.

Similarities with accordions and carousels

Although tablists, accordions, and carousels appear visually different, they all address the same fundamental use case: controlling the visibility of related content sections.

Tablists provide the most basic pattern: one active panel at a time.
Carousels extend this pattern with previous/next controls and optional autoplay.
Accordions stack controls and panels vertically and may allow multiple panels to be open simultaneously.

Because of these similarities, many of the following principles also apply to:

Proofs of concept

Before continuing, please read What is a "Proof of Concept"? (POC).

ARIA-based tablists are well supported across modern browsers and assistive technologies. When native HTML elements cannot express the required behaviour, an ARIA-based implementation is recommended.

POC #1: ARIA (Recommended)

This implementation follows the
WAI-ARIA Authoring Practices Guide for Tabs
and uses manual activation. Users activate a focused tab using Enter, Space, or a mouse click.

Manual activation is recommended when panel content cannot be displayed instantly or when activating a tab triggers expensive operations.

The implementation uses appropriate:

Roles: tablist, tab, tabpanel
States: aria-selected
Relationships: aria-controls, aria-labelledby

This ensures reliable screen reader support across browsers and platforms.

Tablist with ARIA

Show HTML code

Show CSS code

Show JS code

✔ (pass) ,

✔ (pass)

<p>
  <button>Focusable element before</button>
</p>

<section class="tablist-widget">
  <h2 id="flowers-heading">Flowers</h2>

  <div role="tablist" aria-labelledby="flowers" class="tablist">
    <button role="tab" id="t1" aria-controls="p1">Rose</button>
    <button role="tab" id="t2" aria-controls="p2">Tulip</button>
    <button role="tab" id="t3" aria-controls="p3">Sunflower</button>
  </div>

  <div role="tabpanel" id="p1" aria-labelledby="t1">
    <h3>Rose</h3>

    <p>A rose is a woody perennial flowering plant of the genus Rosa.</p>

    <p>
      <a href="https://en.wikipedia.org/wiki/Rose" target="_blank">Learn more about roses</a>
    </p>
  </div>

  <div role="tabpanel" id="p2" aria-labelledby="t2" hidden>
    <h3>Tulip</h3>

    <p>Tulips are a genus of spring-blooming perennial plants.</p>

    <p>
      <a href="https://en.wikipedia.org/wiki/Tulip" target="_blank">Learn more about tulips</a>
    </p>
  </div>

  <div role="tabpanel" id="p3" aria-labelledby="t3" hidden>
    <h3>Sunflower</h3>

    <p>A sunflower is a large annual plant.</p>

    <p>
      <a href="https://en.wikipedia.org/wiki/Sunflower" target="_blank">Learn more about sunflowers</a>
    </p>
  </div>
</section>

<p>
  <button>Focusable element after</button>
</p>

body {
  padding: 20px;
  font-family: system-ui, sans-serif;
}

.tablist {
  display: flex;
  border-bottom: 1px solid #000;
}

[role="tab"] {
  appearance: none;
  background: none;
  border: 1px solid #000;
  border-bottom: none;
  padding: 6px 12px;
  margin: 0 2px 0 0;
  cursor: pointer;
}

[role="tab"][aria-selected="true"] {
  background: lightyellow;
  font-weight: 600;
}

[role="tab"]:hover {
  text-decoration: underline;
}

[role="tab"]:focus-visible {
  outline: 2px dotted;
  outline-offset: 2px;
}

[role="tabpanel"] {
  border: 1px solid #000;
  padding: 1rem;
  background: lightyellow;
}

[role="tabpanel"][hidden] {
  display: none;
}

a:focus-visible,
button:focus-visible {
  outline: 2px dotted;
  outline-offset: 2px;
}

'use strict'

/*
 * Tabs (Manual Activation)
 * WAI-ARIA Authoring Practices compliant
 * https://www.w3.org/WAI/ARIA/apg/patterns/tabs/
 */

class TabList {
  constructor(tablist) {
    this.tablist = tablist

    this.tabs = [...tablist.querySelectorAll('[role="tab"]')]

    this.panels = this.tabs.map(tab =>
      document.getElementById(tab.getAttribute('aria-controls'))
    )

    this.init()
  }

  init() {
    this.tabs.forEach((tab, i) => {
      tab.tabIndex = -1
      tab.setAttribute('aria-selected', 'false')

      tab.addEventListener('click', () => this.activate(i))
      tab.addEventListener('keydown', e => this.onKey(e, i))
    })

    this.activate(0, false)
  }

  activate(i, focus = true) {
    this.tabs.forEach((tab, n) => {
      const active = i === n

      tab.tabIndex = active ? 0 : -1
      tab.setAttribute('aria-selected', active)

      this.panels[n].toggleAttribute('hidden', !active)
    })

    if (focus) this.tabs[i].focus()
  }

  focus(i) {
    const max = this.tabs.length - 1

    if (i < 0) i = max
    if (i > max) i = 0

    this.tabs[i].focus()
  }

  onKey(e, i) {
    const keys = {
      ArrowLeft: () => this.focus(i - 1),
      ArrowRight: () => this.focus(i + 1),
      Home: () => this.focus(0),
      End: () => this.focus(this.tabs.length - 1),
      Enter: () => this.activate(i),
      ' ': () => this.activate(i)
    }

    if (!keys[e.key]) return

    keys[e.key]()
    e.preventDefault()
  }
}

/* Init */

window.addEventListener('DOMContentLoaded', () => {
  document.querySelectorAll('[role="tablist"]').forEach(el => new TabList(el))
})

Category	Result	Comments	Date
Keyboard only	✔ (pass) pass	-	2026-2-5
NVDA 2023.1 + FF 115	✔ (pass) pass	-	2026-2-5
NVDA 2023.1 + Edge	✔ (pass) pass	-	2026-2-5
JAWS 2023.23 + Edge	✔ (pass) pass	-	2026-2-5

Implementation details

Uses the roving tabindex pattern:
- Active tab: tabindex="0"
- Inactive tabs: tabindex="-1"
Keyboard interaction:
- Arrow Left/Right: Move focus between tabs
- Home/End: Move focus to first/last tab
- Enter/Space: Activate focused tab
- Tab: Move focus out of the tablist
Tabs are laid out horizontally using flexbox.
Activation logic ensures that only the selected panel is visible at a time.
Inactive panels are hidden using the hidden attribute to ensure proper support in assistive technologies.
In some implementations, tab elements use display: block (instead of inline-block) to improve navigation in NVDA browse mode.
ARIA attributes establish clear relationships between tabs and panels.

POC #2: Radio buttons (Legacy)

Note: This approach is deprecated and provided for reference only.

The ARIA-based implementation (POC #1) should be used for all new projects, as it offers correct semantics and more reliable support for modern assistive technologies.

The radio button approach was previously used as a simpler alternative based on native form controls. However, radio buttons represent form input choices rather than navigational relationships between tabs and panels. This semantic mismatch leads to poorer screen reader support and inconsistent interaction patterns, requiring significant workarounds to achieve comparable accessibility.

Tablist with radio buttons (Legacy)
(Legacy — for reference only)