Accessible tabs

Why this pattern keeps breaking

Tabs are the second-most-common custom widget after modals, and the second-most-common to fail accessibility review. The visual pattern is obvious — a row of headers, a panel below, the active one highlighted. The behavioural contract is what gets dropped: the tab list has to be a single tab stop, arrow keys move between tabs, Tab moves into the panel, the right ARIA roles and state attributes have to be wired up, and the active tab has to be visually distinguishable in a way that doesn't rely on colour alone.

How AI coding tools fail this

Ask any AI assistant for "a tabs component" and you'll get a row of <button> elements that toggle a visible panel. The visual is correct. The keyboard contract is almost always missing in one of three ways:

Every tab is in the natural tab order, so Tab cycles through every tab instead of moving past the tablist into the panel. WCAG 2.1.1 passes; usability fails.
Arrow keys do nothing. The ARIA APG requires Left/Right (or Up/Down for vertical tabs) to move focus between tabs without leaving the tablist. Without that, the widget doesn't behave like the user expects from native tabs anywhere else.
aria-selected is set on the active tab but not unset on the others, or vice versa. The screen reader hears "selected" or "not selected" in inconsistent places and stops being able to tell what state the widget is in.

A subtler one: the active tab's only visual distinction is a colour change that fails 3:1 contrast against the inactive tabs. Sighted users with low vision can't tell which tab is open.

Canonical implementation

The right answer for most product teams: use a vetted library. Radix UI Tabs (opens in new tab), Headless UI Tab (opens in new tab), and React Aria Tabs (opens in new tab) all ship the keyboard contract, focus management, and ARIA attributes correctly out of the box.

A minimal Radix-based tabs setup that meets the contract:

import * as Tabs from "@radix-ui/react-tabs";

export function ProjectTabs() {
  return (
    <Tabs.Root defaultValue="overview">
      <Tabs.List aria-label="Project sections" className="flex border-b">
        <Tabs.Trigger value="overview" className="px-4 py-2 data-[state=active]:border-b-2 data-[state=active]:border-primary">
          Overview
        </Tabs.Trigger>
        <Tabs.Trigger value="activity" className="px-4 py-2 data-[state=active]:border-b-2 data-[state=active]:border-primary">
          Activity
        </Tabs.Trigger>
        <Tabs.Trigger value="settings" className="px-4 py-2 data-[state=active]:border-b-2 data-[state=active]:border-primary">
          Settings
        </Tabs.Trigger>
      </Tabs.List>

      <Tabs.Content value="overview" className="pt-6">Overview panel.</Tabs.Content>
      <Tabs.Content value="activity" className="pt-6">Activity panel.</Tabs.Content>
      <Tabs.Content value="settings" className="pt-6">Settings panel.</Tabs.Content>
    </Tabs.Root>
  );
}

This satisfies the contract automatically: arrow keys move between tabs, Home and End jump to the first and last, Tab moves into the panel, the active tab gets aria-selected="true" and a 2px border that meets 3:1 contrast, and the inactive tabs report aria-selected="false".

Failing example

A hand-rolled tabs implementation that misses the keyboard contract:

function Tabs({ tabs }: { tabs: { id: string; label: string; body: ReactNode }[] }) {
  const [active, setActive] = useState(tabs[0].id);
  return (
    <div>
      <div className="flex border-b">
        {tabs.map(t => (
          <button
            key={t.id}
            onClick={() => setActive(t.id)}
            className={active === t.id ? "border-b-2 border-blue-400" : ""}
          >
            {t.label}
          </button>
        ))}
      </div>
      {tabs.map(t => active === t.id && <div key={t.id}>{t.body}</div>)}
    </div>
  );
}

What's missing: role="tablist", role="tab", role="tabpanel", aria-selected, aria-controls, tabIndex management so only the active tab is in the page tab order, arrow-key handling, Home/End handling, accessible names tying tabs to panels, sufficient contrast on the active-state border, focus indicator on each tab.

Minimum viable hand-roll

If you can't reach for a library, this is the minimum that gets the core contract right — roles, selected state, arrow-key navigation, and roving tabindex. It is not a complete implementation; for production, use Radix or Headless UI.

import { useRef, useState, type KeyboardEvent } from "react";

type Tab = { id: string; label: string; body: React.ReactNode };

export function Tabs({ tabs, label }: { tabs: Tab[]; label: string }) {
  const [active, setActive] = useState(tabs[0].id);
  const refs = useRef<Record<string, HTMLButtonElement | null>>({});

  function focusByOffset(currentId: string, delta: number) {
    const i = tabs.findIndex(t => t.id === currentId);
    const next = tabs[(i + delta + tabs.length) % tabs.length];
    setActive(next.id);
    refs.current[next.id]?.focus();
  }

  function onKey(e: KeyboardEvent<HTMLButtonElement>, id: string) {
    if (e.key === "ArrowRight") focusByOffset(id, 1);
    else if (e.key === "ArrowLeft") focusByOffset(id, -1);
    else if (e.key === "Home") { setActive(tabs[0].id); refs.current[tabs[0].id]?.focus(); }
    else if (e.key === "End") { setActive(tabs[tabs.length - 1].id); refs.current[tabs[tabs.length - 1].id]?.focus(); }
    else return;
    e.preventDefault();
  }

  return (
    <div>
      <div role="tablist" aria-label={label} className="flex border-b">
        {tabs.map(t => {
          const selected = active === t.id;
          return (
            <button
              key={t.id}
              ref={el => { refs.current[t.id] = el; }}
              role="tab"
              id={`tab-${t.id}`}
              aria-controls={`panel-${t.id}`}
              aria-selected={selected}
              tabIndex={selected ? 0 : -1}
              onClick={() => setActive(t.id)}
              onKeyDown={e => onKey(e, t.id)}
              className={
                "px-4 py-2 focus-visible:ring-2 focus-visible:ring-primary " +
                (selected ? "border-b-2 border-primary font-semibold" : "")
              }
            >
              {t.label}
            </button>
          );
        })}
      </div>
      {tabs.map(t => (
        <div
          key={t.id}
          role="tabpanel"
          id={`panel-${t.id}`}
          aria-labelledby={`tab-${t.id}`}
          hidden={active !== t.id}
          tabIndex={0}
          className="pt-6 focus-visible:ring-2 focus-visible:ring-primary"
        >
          {t.body}
        </div>
      ))}
    </div>
  );
}

This gets the contract right but still doesn't handle vertical tab lists, automatic activation, or scrollable tab strips. For any of those, use a library.

Verification checklist

Before shipping any tab component, manually verify each of these:

Tab into the tab list — focus lands on the active tab only, not the first tab in the list.
Press Right arrow — focus moves to the next tab; the previous tab is no longer in the tab order.
Press Left arrow at the first tab — focus wraps to the last.
Press Home — focus moves to the first tab.
Press End — focus moves to the last tab.
Press Tab from any active tab — focus moves into the panel, not to the next tab.
With a screen reader running, open the tabs — the active tab is announced as selected, inactive tabs as not selected.
Inspect the active-state border or background — it meets 3:1 contrast against the inactive-state colour.

Why this pattern keeps breaking

How AI coding tools fail this

Canonical implementation

Verification checklist

WCAG criteria this pattern satisfies

References