Design a tabs component

Requirements: what to ask before drawing anything

Tabs are a set of buttons in a row, called the tab list, where each button shows one panel of content and hides the others. Only one panel is visible at a time. You've used them on a product page (Overview, Reviews, Specs), in a settings screen, and in every code editor.

Tabs look like the easiest component in a design system: a few buttons and a useState. That's why interviewers like them.

A junior answer stops at the buttons. A senior answer asks what the panels contain, where the selected tab is stored, how a keyboard user moves between tabs, and what happens on a small screen. Each of those questions turns into a real decision with trade-offs.

Start by asking questions. The middle column is what this guide assumes. The right column is why the answer matters.

Functional requirements

• Show a list of tabs and exactly one visible panel. Clicking or tapping a tab shows its panel.
• Work fully from the keyboard: Tab moves into the tab list and then to the panel, arrow keys move between tabs, Home and End jump to the first and last tab.
• Support disabled tabs that can't be selected, with a reason shown nearby.
• Support horizontal and vertical layouts.
• Work uncontrolled (the component remembers the selected tab) and controlled (the page passes the selected value, for example from the URL).
• Let the page choose what happens to hidden panels: unmount them, keep them mounted but hidden, or render them only once they've been visited.
• Stay usable when the tabs don't fit: scroll, collapse into a menu, or switch to another layout.

Non-functional requirements

• Fast switching. A tab change should paint within one frame or two (under about 50 ms) for content that's already loaded, well inside the 200 ms budget for a good Interaction to Next Paint (INP), the Core Web Vital that measures how quickly the page responds to input.
• Small. The core (without the indicator animation) should be a few kilobytes gzipped, because it ships on product pages where every kilobyte counts.
• Accessible. Correct roles and states, visible focus, no keyboard traps, and motion that respects prefers-reduced-motion.
• No layout shift. Switching tabs or loading a panel must not push the page around in ways that count toward Cumulative Layout Shift (CLS).
• Server rendering safe. The first HTML shows the right tab with real content, and hydration produces no mismatch warnings.

Out of scope, and why

• Closable and reorderable tabs, like browser tabs or editor tabs. That's a different widget with drag and drop, close buttons, and a tab strip state machine. Mention it, then set it aside.
• Site navigation that looks like tabs but loads a new page for each item. We'll come back to this one in chapter 9, because choosing the wrong pattern is a common accessibility bug.
• The content of each panel. We design the container, not the reviews list inside it.

What makes tabs harder than they look

Here's the naive version most people write first. It works for a mouse user on a laptop, and it breaks in at least six ways.

function Tabs({ labels, children }) {
  const [index, setIndex] = useState(0);
  return (
    <div>
      {labels.map((label, i) => (
        <button key={label} onClick={() => setIndex(i)}
          className={i === index ? "active" : ""}>
          {label}
        </button>
      ))}
      {children[index]}
    </div>
  );
}

• A screen reader hears six unrelated buttons. Nothing says they're tabs, which one is selected, or which content they control. The active class is only visual.
• The keyboard walks every tab. Pressing Tab stops on each button before reaching the content. With 6 tabs, a keyboard user presses Tab 6 times to get past them, on every visit.
• Switching tabs throws away work. children[index] unmounts the old panel. A half-typed review, a scroll position, and a loaded chart are all gone when you come back.
• The index is fragile. Store 2 in the URL and then marketing adds a "Q&A" tab at position 1. Every shared link now opens the wrong tab.
• Nobody else can see the state. The URL doesn't change, so refresh, back, and shared links all land on the first tab.
• It doesn't fit on a phone. Six buttons in a row wrap onto two lines or overflow off the right edge, and the selected one may be off screen.

So the problem has five forces that drive every later chapter:

The component API: who owns the selected tab

The API is the first thing other teams touch, and the hardest thing to change later. The component API design lesson covers the general rules; here we apply them to tabs. There are three common shapes.

<Tabs defaultValue="overview" activation="automatic">
  <TabList aria-label="Product details">
    <Tab value="overview">Overview</Tab>
    <Tab value="reviews">Reviews <Badge>212</Badge></Tab>
    <Tab value="specs">Specs</Tab>
    <Tab value="qa" disabled>Q&A</Tab>
  </TabList>
  <TabPanel value="overview" mount="eager">...</TabPanel>
  <TabPanel value="reviews" mount="lazy">...</TabPanel>
  <TabPanel value="specs">...</TabPanel>
  <TabPanel value="qa">...</TabPanel>
</Tabs>

String values, not indexes

Each Tab and TabPanel pair shares a value like "reviews". The naive version used positions. Positions break when a tab is added, removed, reordered, or hidden behind a feature flag, and they make URLs meaningless (?tab=2).

A string survives all of that, reads well in a URL (?tab=reviews), and shows up clearly in analytics events. It also lets a Tab and its TabPanel sit far apart in the tree, for example when the tab list is in a sticky header.

Controlled and uncontrolled

An uncontrolled component keeps its own state: you pass defaultValue once and it remembers the selection. A controlled component gets the current value from its parent on every render and calls onValueChange to ask the parent to change it. Docs code samples want the first. A product page that keeps the tab in the URL wants the second, because the URL is the owner.

Support both with one small hook. If value is passed, use it and never store a copy; otherwise keep internal state seeded from defaultValue. Switching between the two modes during the component's life is a bug in the caller, so warn in development, the way React warns for inputs.

function useControllable<T>(value: T | undefined, defaultValue: T,
  onChange?: (next: T) => void) {
  const [inner, setInner] = useState(defaultValue);
  const controlled = value !== undefined;
  const current = controlled ? value : inner;
  const set = useCallback((next: T) => {
    if (next === current) return;
    if (!controlled) setInner(next);
    onChange?.(next);
  }, [controlled, current, onChange]);
  return [current, set] as const;
}

Disabled tabs, orientation, and activation

• disabled on a Tab. The tab can't be selected. The APG allows two choices for keyboard focus: skip it or let it receive focus with aria-disabled="true". We keep it focusable, because a screen reader user who can't land on it never learns it exists or why it's off. Pair it with a visible reason, like a tooltip saying "Q&A opens after launch".
• orientation on TabList. "horizontal" (default) or "vertical". It sets aria-orientation and decides which arrow keys move focus.
• activation on Tabs. "automatic" (default) selects a tab as soon as it gets focus; "manual" waits for Enter or Space. Chapter 4 explains when to pick each.
• What if defaultValue points at a disabled or missing tab? Fall back to the first enabled tab and warn in development. A page should never render with no panel shown.

How does a Tab know its neighbors when the user presses the right arrow? The simplest reliable way: at keydown time, ask the tab list element for its [role="tab"] children in DOM order. That order is always what the user sees, even with conditional tabs or tabs wrapped in tooltips.

Registering tabs into an array through context also works but must handle mount order, reordering, and Strict Mode double effects. Reading the DOM on a key press costs microseconds for 11 tabs.

Roles, ids, and the keyboard

Screen reader users have met tabs thousands of times. When the markup follows the WAI-ARIA tabs pattern, their screen reader says something like "Reviews, tab, selected, 2 of 4" and they know the keys without reading anything. The ARIA patterns lesson covers roles and states in general; this chapter is the exact contract for tabs.

Three roles and the links between them

• role="tablist" on the row. It needs a name: aria-label="Product details", or aria-labelledby pointing at a visible heading. Add aria-orientation="vertical" for vertical tabs (horizontal is the default).
• role="tab" on each button, with aria-selected="true" on the selected one and "false" on the rest. aria-controls points at the id of its panel. Use a real button element so clicks, Enter and Space work for free.
• role="tabpanel" on each panel, with aria-labelledby pointing back at its tab, so the panel is announced as "Reviews, tab panel". Hidden panels get the hidden attribute (chapter 5 covers the options).
• tabindex="0" on the panel when its content has no focusable element at the start, like a block of text. Without it, pressing Tab from the tab list jumps past the whole panel to whatever comes next. If the panel starts with a link or a button, leave the panel itself out of the tab order.

<div role="tablist" aria-label="Product details">
  <button role="tab" id="t1-tab-overview" aria-selected="false"
    aria-controls="t1-panel-overview" tabindex="-1">Overview</button>
  <button role="tab" id="t1-tab-reviews" aria-selected="true"
    aria-controls="t1-panel-reviews" tabindex="0">Reviews</button>
  <button role="tab" id="t1-tab-qa" aria-selected="false"
    aria-disabled="true" aria-controls="t1-panel-qa" tabindex="-1">Q&amp;A</button>
</div>
<div role="tabpanel" id="t1-panel-overview"
  aria-labelledby="t1-tab-overview" tabindex="0" hidden>...</div>
<div role="tabpanel" id="t1-panel-reviews"
  aria-labelledby="t1-tab-reviews" tabindex="0">...</div>

One tab stop for the whole row

A tab list is a composite widget: one stop in the Tab order, with arrow keys to move inside it. The keyboard navigation lesson explains the two ways to build one. Roving tabindex gives the current tab tabindex="0" and every other tab tabindex="-1", then moves real DOM focus with element.focus() on each arrow key. aria-activedescendant keeps focus on the container and points at the active child by id.

For tabs, roving tabindex is the clear pick: each tab is a real button that can hold focus, the browser scrolls it into view and draws the focus ring, and it's what the APG examples use.

Arrow keys land on disabled tabs too (we chose to keep them focusable), but never select them. In automatic mode, focus moves to the disabled tab and the selection stays where it was, so the panel never goes blank.

Automatic or manual activation

Right to left. In Arabic and Hebrew, the page sets dir="rtl" and the tab row is mirrored: the first tab is on the right. Right Arrow must still move to the tab that's visually to the right, which is now the previous one in DOM order.

So the key handler reads the direction (getComputedStyle(tablist).direction, or a direction value from your i18n provider) and swaps Left and Right. Up and Down never flip. Libraries such as Radix (through a dir prop) and React Aria (through the locale) do this for you, and forgetting it is a common bug in hand-built tabs.

Ids that match on the server and the client

aria-controls and aria-labelledby need ids, and ids must be unique on the page: two tab sets both using tab-overview break each other. The tempting fix is a random number or a global counter. With server rendering, that fails: the server renders tab-0.42 and the browser computes tab-0.87 during hydration, so React reports a hydration mismatch.

React doesn't promise to patch mismatched attributes, so the DOM can keep the server ids while anything rendered later on the client, like a lazily mounted panel, uses the client ids. The tab now points at a panel id that doesn't exist. The server-side rendering lesson explains hydration and why the server and client trees must match.

React's useId solves this: it builds the id from the component's position in the tree, so the server and the client get the same string. Tabs calls useId once and shares the base through context; each part adds a suffix like -tab-reviews. Two rules: let callers pass their own id to override it, and never parse the generated string or use it in a CSS selector, because its format has changed between React versions. If values can contain spaces, encode them before using them in an id.

What happens to the panels you're not looking at

Only one panel is visible, but the others still exist somewhere: in the DOM, in React's memory, or nowhere at all. This choice decides whether a half-typed form survives a tab switch, how big the DOM is, how many requests fire on page load, and whether find-in-page can see the hidden text. It's the decision that separates a component that demos well from one that works on a real product page.

Take the product page. Overview is about 150 DOM nodes. Reviews shows 50 reviews at about 40 nodes each, so 2,000 nodes, plus a filter form.

Specs is a 60-row table, about 400 nodes, loaded from an API. Q&A is another 1,500 nodes, also from an API. Rendering all four up front means about 4,000 nodes and three API calls before the user has looked at anything but Overview.

How to hide a mounted panel

The hidden attribute is the right default: it's the same as display: none, so the panel takes no layout, no paint, and is removed from the accessibility tree and the tab order. One trap: a CSS rule like .panel { display: grid } overrides it, because the browser's style for hidden is only a default. Add [hidden]:not([hidden="until-found"]) { display: none !important } to the design system's base CSS. The :not() part matters: a plain [hidden] rule would also break the until-found value below, which hides content in a different way.

hidden="until-found" is a newer value that keeps the content hidden but lets the browser search it. When find-in-page, a link to a text fragment, or a link to an id inside it matches, the browser fires a beforematch event on the element, removes the attribute, and scrolls to the match. Browsers draw it with content-visibility: hidden rather than display: none, so the panel's own box, padding, and border stay in the layout: put padding on an inner wrapper.

Support arrived in Chromium browsers in 2022 (version 102), Firefox in 2025 (version 139), and Safari at the end of 2025 (version 26.2). MDN notes that Firefox before 148 and Safari 26.2 don't scroll to the match correctly. Older browsers treat any value of hidden as plain hidden, so it fails safely: treat it as an upgrade, not something you depend on.

For tabs, there's one extra step: in the beforematch handler, select that panel's tab, or the panel shows while the tab list still highlights a different tab. In React, attach that listener with addEventListener in an effect.

React adds one more catch: it treats hidden as a plain boolean, so hidden="until-found" in JSX comes out as hidden="" (React issue 24740, still open in 19.x). Render hidden as a boolean, then set the value with setAttribute("hidden", "until-found") in a layout effect, which runs before paint.

The server HTML still has plain hidden, so find-in-page and links can't reveal a panel until hydration. If that matters, a few lines of inline script right after the tabs' HTML can set the value during parsing. Hydration accepts it, because React only checks that a boolean attribute is present.

Kept-mounted panels keep running. A chart that polls every 5 seconds in a hidden panel still sends 12 requests a minute. Give each panel an isActive value from context so it can pause polling, videos, and animations.

React 19.2 (October 2025) added an Activity component for exactly this case: with mode="hidden" it hides the subtree with display: none, keeps its state and DOM, and cleans up its effects until it's visible again. On React 19.2 or later, the kept-mounted mode can wrap each inactive panel in it.

The URL and the data behind each tab

Marketing shares shop.example/p/123?tab=reviews in an email. A support agent asks a user to "open the Billing tab and read me the number". A user refreshes the page. In all three cases the right tab must open, so the selected tab belongs in the URL.

The URL as state lesson covers the general idea; here we decide where in the URL, and how it interacts with history and data loading.

pushState or replaceState

history.pushState adds a history entry, so Back returns to the previous tab. history.replaceState changes the current entry, so Back leaves the page. With automatic activation, a keyboard user who arrows across 4 tabs and then presses Back would, with push, step back through 4 tabs before leaving the page.

For view tabs, use replace: the URL is always shareable and refresh works, but the history isn't filled with tab visits. Use push only for route-segment tabs that feel like pages. Whichever you choose, listen for popstate (or use the router's search params) so Back and Forward update the selected tab: in controlled mode that happens on its own, because the URL is the owner.

function ProductTabs() {
  const [params, setParams] = useSearchParams();
  const raw = params.get("tab");
  const tab = TABS.includes(raw) ? raw : "overview";

  const onValueChange = (next: string) => {
    const p = new URLSearchParams(params);
    if (next === "overview") p.delete("tab"); else p.set("tab", next);
    setParams(p, { replace: true });
  };

  return (
    <Tabs value={tab} onValueChange={onValueChange}>...</Tabs>
  );
}

Loading data per tab

The naive version keeps one data variable for "the current tab" and calls fetch in an effect whenever the tab changes. Here's how that breaks: the user clicks Reviews, which starts a 900 ms request, and 200 ms later clicks Specs, which starts a 150 ms request. Specs arrives at 350 ms and renders. Reviews arrives at 900 ms and overwrites data, so the Specs panel now shows reviews.

This is a request race, and the request races lesson covers the general fixes. For tabs, a few changes make it go away.

• One cache entry per tab. Each panel owns its query, keyed by what it shows, like ["reviews", productId] and ["specs", productId], in a server-state cache such as TanStack Query. A late Reviews response writes into the Reviews entry and can never land in the Specs panel.
• Show cached data at once, refresh in the background. Coming back to Reviews shows the data from 30 seconds ago immediately, then refetches if it's older than its staleTime. That's stale-while-revalidate: no spinner on the second visit.
• Cancel only what can't be reused. Don't abort the Reviews request when the user leaves; it fills the cache for the next visit. Do abort requests whose parameters changed, like a filter typed into the Reviews panel, with an AbortController.
• Keep the previous data while a parameter changes. When the Reviews filter changes from 5 stars to 4 stars, keep showing the 5-star list, dimmed, until the 4-star list arrives, instead of flashing an empty spinner.

Prefetch on intent. A mouse user's pointer often rests on a tab for a few hundred milliseconds before the click lands. Start the panel's query on pointerenter and on focus; by the time the click arrives, a 200 ms request is mostly done. On touch screens there's no hover, so prefetch the next most likely tab when the browser is idle, or prefetch everything small after the page loads.

Prefetching uses the same cache keys, so a prefetch and a real load never fetch twice. The panel's code can be prefetched the same way, if each heavy panel is a separate chunk loaded with import().

The sliding indicator and tabs that don't fit

The animated selection indicator

Designers often want the underline under the selected tab to slide to the new tab instead of jumping. The simplest version, a border-bottom on the selected tab, can't slide, because each tab draws its own line. So the indicator becomes one separate element inside the tab list, positioned under whichever tab is selected.

To place it, measure the selected tab: its offsetLeft and offsetWidth relative to the tab list. Then move the indicator with transform: translateX(...) and size it with scaleX(...) on a bar that's 1 pixel wide at rest.

Why not animate left and width? Those are layout properties, so every frame of the animation runs layout. A CSS transition on transform can run on the compositor, so the slide stays smooth even if the main thread is busy rendering the new panel, which it usually is at that exact moment.

// The list has position: relative, and the bar sits inside it
// with transform-origin: left, so it scrolls along with the tabs.
function placeIndicator(list: HTMLElement, bar: HTMLElement) {
  const tab = list.querySelector<HTMLElement>('[aria-selected="true"]');
  if (!tab) return;
  const x = tab.offsetLeft;
  bar.style.transform = `translateX(${x}px) scaleX(${tab.offsetWidth})`;
}

const ro = new ResizeObserver(() => placeIndicator(list, bar));
list.querySelectorAll('[role="tab"]').forEach((t) => ro.observe(t));
ro.observe(list);

Measuring once on selection is not enough. Tab widths change when the web font finishes loading (the fallback font is narrower or wider), when the language changes, when a badge count goes from 9 to 10, and when the window resizes. A ResizeObserver on each tab and on the list catches all of these.

For vertical tabs, measure offsetTop and offsetHeight and use translateY and scaleY. In right-to-left layouts, offsetLeft is still measured from the left edge, so the same math works.

• Reduced motion. Wrap the transition in @media (prefers-reduced-motion: no-preference), so users who asked for less motion get an instant jump. The visual accessibility lesson covers why sliding motion can make some people feel ill.
• Don't rely on the indicator alone. Selected tabs benefit from a second cue, like bold text or a stronger color, with at least 3:1 contrast for the indicator against its background. Forced colors mode (Windows High Contrast) replaces background colors and removes shadows, so a bar drawn with background-color can vanish: draw it with a border, or give it the Highlight system color inside @media (forced-colors: active).
• Server rendering. Measurement only works in the browser. Render the first position with plain CSS (a border on the selected tab), then switch to the sliding bar after hydration, so there's no missing indicator in the first paint.
• A CSS-only future. CSS anchor positioning can tie the bar to the selected tab with no JavaScript measuring. It reached the last major engine only in early 2026 (Firefox 147), so treat it as an upgrade behind @supports, not the base, until your users' browsers catch up.

When the tabs don't fit

Five tabs averaging 100 pixels need 500 pixels. A phone in portrait gives you about 360 pixels minus padding, and German labels are often 30% longer than English ones. You can't just let the row wrap onto two lines: it looks like two separate tab lists and the indicator has nowhere to sit.

Architecture, state, and the public interface

Now put the decisions together. The key boundary: the tabs component knows nothing about the URL, the router, or the API. It owns selection, focus, ARIA, and mounting.

The page owns where the value is stored and what each panel loads. That keeps the component small, testable without a server, and usable on pages that don't route at all, like a docs code sample.

The client data model

A tabs component has little data, but each piece has a clear home, and putting one in the wrong place causes the bugs we've seen. The selected value lives in the URL (controlled) or in Tabs state (uncontrolled). The focused tab is not React state at all: it's wherever DOM focus is, and storing a copy only creates a second truth that drifts.

The set of visited panels lives in the root, so lazy panels know they've been opened. Panel data lives in the query cache, keyed per panel. Form state inside a panel lives in that panel if it's kept mounted, or above Tabs if it must survive unmounting.

type Orientation = "horizontal" | "vertical";
type Activation = "automatic" | "manual";
type MountMode = "eager" | "lazy" | "unmount";

type TabsContextValue = {
  baseId: string;            // from useId(), or the caller's id
  selected: string;          // the one source of truth for selection
  select: (value: string, reason: ChangeReason) => void;
  orientation: Orientation;
  activation: Activation;
  visited: ReadonlySet<string>; // panels opened at least once
  reportIntent?: (value: string) => void; // hover or focus, for prefetch
};

type ChangeReason = "click" | "keyboard" | "find-in-page";

const tabId = (base: string, v: string) => `${base}-tab-${encodeURIComponent(v)}`;
const panelId = (base: string, v: string) => `${base}-panel-${encodeURIComponent(v)}`;

The public interface

Tabs or links, and how to test it all

When a tab bar should be links

Look at the bar at the top of a GitHub repository: Code, Issues, Pull requests, Actions. It looks like tabs. But each item goes to a different URL with its own page, and you can middle-click one to open it in a new browser tab. That's navigation, and it's built as links inside a nav, with aria-current="page" on the current one.

If it used the tabs pattern instead, three things would break.

• The keyboard model lies. A screen reader says "tab, 1 of 4", so the user presses Right Arrow and expects a panel to change in place. Instead, a whole page loads and focus resets to the top.
• Links stop being links. Buttons can't be opened in a new browser tab, copied as a link, or shown in the browser's status bar on hover.
• There's no panel. aria-controls must point at a tab panel on the same page. After a full navigation, the old tab list is gone.

The rule: if choosing an item changes the path to a different page, or users might want to open it in a new browser tab, use links with aria-current="page", styled however the designers like. If choosing an item swaps content within the same page and the user stays in place, use the tabs pattern. The ?tab= query parameter from chapter 6 doesn't change this: the page and its focus stay put, so it's still tabs.

<nav aria-label="Repository">
  <a href="/acme/app" aria-current="page">Code</a>
  <a href="/acme/app/issues">Issues</a>
  <a href="/acme/app/pulls">Pull requests</a>
</nav>

Testing

Most of a tabs component's value is behavior: roles, focus, keys, and mounting. So most tests should drive it the way users do, through roles and the keyboard, not by checking class names.

test("arrow keys move focus and select in automatic mode", async () => {
  const user = userEvent.setup();
  render(<ProductTabs />);
  await user.tab();
  expect(screen.getByRole("tab", { name: "Overview" })).toHaveFocus();

  await user.keyboard("{ArrowRight}");
  const reviews = screen.getByRole("tab", { name: /Reviews/ });
  expect(reviews).toHaveFocus();
  expect(reviews).toHaveAttribute("aria-selected", "true");
  expect(screen.getByRole("tabpanel", { name: /Reviews/ })).toBeVisible();

  await user.keyboard("{End}");
  expect(screen.getByRole("tab", { name: "Q&A" })).toHaveFocus();
  expect(reviews).toHaveAttribute("aria-selected", "true"); // Q&A is disabled
});

Running it in the interview

Tabs is usually a 30 minute question, sometimes the warm-up to a bigger one. The risk isn't running out of ideas; it's spending 20 minutes on CSS. Here's one way to spend the time.

Draw three things, in this order: the wireframe with the parts named, the ARIA wiring, and the architecture with the boundary between the component and the page. Everything else can be said out loud. When you make a choice, say the alternative you rejected and the number that decided it, for example "lazy then keep, because eager costs about 4,000 nodes and three requests that most visitors never use". That sentence is worth more than any amount of extra detail.

Follow-up questions to expect