Skip to content

Tabs

import { useTabs } from "@katanakit/ui";
const tabs = useTabs({
label: "Account settings",
tabs: [
{ id: "profile", label: "Profile", content: "…" },
{ id: "billing", label: "Billing" },
],
});
document.body.append(tabs.root);

Built on the WAI-ARIA tabs pattern: role="tablist" over role="tab" buttons, each owning a role="tabpanel".

A tablist is one composite widget, not a list of independent controls. The user tabs into it once and then uses ←/→ to move between tabs. Giving every tab tabindex="0" would put N stops in the page’s tab order for what is conceptually a single control — and a keyboard user would have to press Tab N times just to get past the group.

So the selected tab carries tabindex="0" and the rest carry tabindex="-1". Pressing Tab once leaves the whole widget.

::: tip Panels are always keyboard reachable Every panel gets tabindex="0". A panel containing nothing focusable would otherwise be unreachable — the user selects a tab, focus stays on the tab, and they can never read what it revealed. :::

activation: "automatic" (the default) selects a tab the moment it receives focus. That is what most users expect from tabs.

activation: "manual" moves focus with the arrows but requires Enter or Space to commit. Use it when selecting a tab is expensive, or when it would change the URL.

Key Action
← / → Previous / next enabled tab, wrapping around.
Home / End First / last enabled tab.
Enter / Space Commit, in manual mode only.
Tab Leave the whole widget.

Disabled tabs are skipped in both directions and ignored on click.

Option Type Default Notes
tabs TabDefinition[] — The tabs, in order.
label string "Tabs" Accessible name for the tablist.
active string first enabled tab Id of the initially selected tab.
activation "automatic" | "manual" "automatic" Selection follows focus, or not.
onChange (id: string) => void — Called when the selected tab changes.

A TabDefinition is { id, label, content?, disabled? }. content accepts a string (inserted with textContent, never parsed as HTML) or a Node; omit it to render the panel yourself.

const { root, list, buttons, panels, select } = useTabs({
tabs,
label: "Sections",
});
document.body.append(root);
select("billing"); // select without moving focus

useTabs needs a DOM. tabsClass() is pure and safe to call on the server.