Tabs

Overview

Tabs swap one view for another inside the same surface. They do not navigate to another page; they do not act on selection; they do not configure anything. Reach for them when the user needs to see the same object through different lenses — a customer's orders vs. their settlements, an invoice's timeline vs. its line items. If pressing the tab changes the URL, the page, or the object the user is looking at, you want a link, not a tab.

Anatomy

A label, a baseline, and a 2 px stroke that thickens under the active tab. The simplest indicator pattern in the system.

The row uses a 28 px gap between items and a fixed 40 px height. Tab items pad 16 px top and bottom internally; the stroke and baseline live inside that padding so the visual rhythm of the surrounding page never shifts when the user changes tabs.

States

Five states cover every interaction. Hover and active are deliberately quiet — the tab is a navigation surface, and over- decorated hover states pull focus away from the content the user is actually trying to read.

Badges

Two badge slots — never both at once. The count is a hard number the user should act on; the “New” pill is a single- shot announcement of an unseen tab.

Density

Two is the floor, six is the ceiling. The 28 px gap is fixed, which means the row needs to fit on the smallest surface it ever renders on — typically a 1024 px column inside the portal.

In product

Tabs at the top of a panel, with content below. The tab row sits inside the same card as its panel; the bottom baseline visually attaches to the panel surface so the two read as one object.

Overflow

Tabs do not scroll, do not stack, and do not collapse to a “More” menu. If the tabs don't fit, the composition is wrong, not the component.

Behavior

• 01Click swaps the panel only. The page URL, scroll position, and surrounding controls stay put. If the tab needs to be deep-linkable, mirror it into the query string (?tab=transactions) — but the click itself never triggers a navigation.
• 02Default to the first tab. On first load, the leftmost tab is selected. Persist the user's last choice across sessions only when the tabs represent a workflow the user returns to (Inbox vs. Drafts) — never for views (Overview vs. Forecasts) where stale state is confusing.
• 03Selection is instant. The panel swaps in the same frame as the click. If the new panel needs data, render the panel skeleton inside the panel area, not inside the tab — the tab indicator should never sit in a loading state.
• 04Disabled tabs are forbidden. If a view doesn't apply to the user, hide the tab. A row of items with one greyed out forces every user to read the tooltip explaining why; better to render a smaller row.
• 05Counts update live. When a tab's count changes (a new dispute arrives), the badge updates in place — no animation, no flash. The user learns to glance at the row to check for new work.

Accessibility

• Roles: the row is role="tablist"; each tab is role="tab" with aria-selected; the panel below is role="tabpanel" labelled by the active tab.
• Keyboard: ← / → moves between tabs; Home / End jumps to the first / last; Enter and Space activate.Tab moves focus into the panel — never between tabs.
• Focus visibility: the focus state shows a 2 px ring in border.selected wrapping the tab. The ring is suppressed on click (use :focus-visible) so the indicator only appears for keyboard users.
• Badge announcements: a count badge is read as part of the tab name — "Disputes, 3" — using aria-label on the tab. Don't leave the badge as visual-only; counts are often the reason the user is here.
• Reduced motion: there is no entrance or indicator animation by default. If the project adds a sliding indicator, gate it behind prefers-reduced-motion: no-preference.

Code

The component composes from a Tabs wrapper and a single Tab primitive. The wrapper carries the row state; the tab is a button that renders its label and optional badge.

import { Tabs, TabPanel } from "@flatpay-dk/ui";

const items = [
  { label: "Overview" },
  { label: "Transactions" },
  { label: "Forecasts", newBadge: true },
  { label: "Disputes", count: 3 },
] as const;

const [tab, setTab] = useState(0);

return (
  <section className="rounded-2xl border bg-card">
    <div className="px-6 pt-6">
      <Tabs
        items={items}
        value={tab}
        onChange={setTab}
        ariaLabel="Reports"
      />
    </div>
    <TabPanel label={items[tab].label} className="px-6 py-6">
      {/* Panel contents — render based on items[tab].label */}
    </TabPanel>
  </section>
);

// Mirror to the URL when the tabs need to be deep-linkable
const router = useRouter();
const search = useSearchParams();
const active = items.findIndex((i) => i.label === search.get("tab"));

<Tabs
  items={items}
  value={active === -1 ? 0 : active}
  onChange={(i) => router.replace(`?tab=${items[i].label}`)}
  ariaLabel="Reports"
/>

Best practices

Tabs are easy to over-use. The questions below catch the most common misfires before they reach the screen.

Props

Tabs

Tab

Related