A list of tabs that show one panel at a time, or the same list as links to other pages.
<div class="cap-tabs" data-cap="tabs" id="tabs-default">
<div class="cap-tabs-list" role="tablist" aria-label="Site sections">
<button type="button" class="cap-tab" role="tab" id="td-overview" aria-selected="true" aria-controls="tdp-overview" tabindex="0">Overview</button>
<button type="button" class="cap-tab" role="tab" id="td-runs" aria-selected="false" aria-controls="tdp-runs" tabindex="-1">Runs<span class="cap-tab-count">24</span></button>
<button type="button" class="cap-tab" role="tab" id="td-alerts" aria-selected="false" aria-controls="tdp-alerts" aria-disabled="true" tabindex="-1">Alerts</button>
<button type="button" class="cap-tab" role="tab" id="td-settings" aria-selected="false" aria-controls="tdp-settings" tabindex="-1">Settings</button>
</div>
<div class="cap-tabs-panel" role="tabpanel" id="tdp-overview" aria-labelledby="td-overview" tabindex="0">
<p>example.org is up. The last check ran at 14:02 and took 212 ms.</p>
</div>
<div class="cap-tabs-panel" role="tabpanel" id="tdp-runs" aria-labelledby="td-runs" tabindex="0" hidden>
<p>24 runs in the last day. The most recent, job_7c21, finished at 14:02.</p>
</div>
<div class="cap-tabs-panel" role="tabpanel" id="tdp-alerts" aria-labelledby="td-alerts" tabindex="0" hidden>
<p>Alerts are off for this site.</p>
</div>
<div class="cap-tabs-panel" role="tabpanel" id="tdp-settings" aria-labelledby="td-settings" tabindex="0" hidden>
<p>Check every 5 minutes from two regions.</p>
</div>
</div>
Installation
// package.json: "capsomer": "github:DrDustinEdwards/capsomer#v0.152.2"
import "capsomer/tokens.css";
import "capsomer/base.css";
import "capsomer/tabs.css";
import { enhance } from "capsomer/behavior/tabs";
enhance();import "capsomer/tokens.css";
import "capsomer/tabs.css";
import { Tabs, TabsList, TabsTrigger, TabsContent, TabsNav, TabLink, PageTabs } from "capsomer/react/tabs";Usage
<div class="cap-tabs" data-cap="tabs">
<div class="cap-tabs-list" role="tablist" aria-label="Site sections">
<button type="button" class="cap-tab" role="tab" id="t-overview" aria-selected="true" aria-controls="p-overview" tabindex="0">Overview</button>
<button type="button" class="cap-tab" role="tab" id="t-runs" aria-selected="false" aria-controls="p-runs" tabindex="-1">Runs<span class="cap-tab-count">24</span></button>
</div>
<div class="cap-tabs-panel" role="tabpanel" id="p-overview" aria-labelledby="t-overview" tabindex="0">...</div>
<div class="cap-tabs-panel" role="tabpanel" id="p-runs" aria-labelledby="t-runs" tabindex="0" hidden>...</div>
</div>
<nav class="cap-tabs-list" data-variant="line" aria-label="Filter posts by status">
<a class="cap-tab" href="/admin/posts" aria-current="page">All<span class="cap-tab-count">312</span></a>
<a class="cap-tab" href="/admin/posts?status=draft">Drafts<span class="cap-tab-count">21</span></a>
</nav><div class="cap-tabs" data-cap="tabs" data-progressive data-remember="platform" data-remember-guess="platform">
<div class="cap-tabs-list" data-variant="line" data-label="Platform">
<a class="cap-tab" href="#install-macos" data-value="macos">macOS</a>
<a class="cap-tab" href="#install-windows" data-value="windows">Windows</a>
</div>
<div class="cap-tabs-panel" id="install-macos"><p class="cap-tabs-panel-label">macOS</p>...</div>
<div class="cap-tabs-panel" id="install-windows"><p class="cap-tabs-panel-label">Windows</p>...</div>
</div><Tabs defaultValue="overview">
<TabsList aria-label="Site sections" variant="line">
<TabsTrigger value="overview">Overview</TabsTrigger>
<TabsTrigger value="runs" count={24}>Runs</TabsTrigger>
<TabsTrigger value="alerts" disabled>Alerts</TabsTrigger>
</TabsList>
<TabsContent value="overview">...</TabsContent>
<TabsContent value="runs">...</TabsContent>
</Tabs>
<TabsNav aria-label="Filter mentions by status">
<TabLink href="?status=open" current count={12}>Open</TabLink>
<TabLink href="?status=resolved" count={48}>Resolved</TabLink>
</TabsNav><Tabs defaultValue="macos" remember="platform" rememberGuess="platform">...</Tabs>
<Tabs defaultValue="simple">
<TabsList aria-label="Markup view" variant="pill">
<TabsTrigger value="original" tone="info">Original</TabsTrigger>
<TabsTrigger value="simple" tone="ok">Simple markup</TabsTrigger>
</TabsList>
...
</Tabs>
const search = useLocation().search;
<PageTabs aria-label="Agents" path="/agents" search={search} current={tabParam(search) ?? "active"}
tabs={[{ id: "active", label: "Active", count: 3 }, { id: "history", label: "History" }]}
renderLink={({ href, ...props }) => <Link to={href} {...props} />} />import { TabsNav, TabLink } from "capsomer/react/tabs";
import { Link } from "react-router";
<TabsNav aria-label="Filter mentions by status" renderLink={({ href, ...props }) => <Link to={href} {...props} />}>
<TabLink href="/mentions/all" current={status === "all"} count={24}>All</TabLink>
<TabLink href="/mentions/waiting" current={status === "waiting"} count={5}>Waiting</TabLink>
</TabsNav>Examples
Line variant
<div class="cap-tabs" data-cap="tabs" id="tabs-line">
<div class="cap-tabs-list" role="tablist" aria-label="Post views" data-variant="line">
<button type="button" class="cap-tab" role="tab" id="tl-draft" aria-selected="true" aria-controls="tlp-draft" tabindex="0">Draft</button>
<button type="button" class="cap-tab" role="tab" id="tl-preview" aria-selected="false" aria-controls="tlp-preview" tabindex="-1">Preview</button>
<button type="button" class="cap-tab" role="tab" id="tl-history" aria-selected="false" aria-controls="tlp-history" tabindex="-1">History<span class="cap-tab-count">7</span></button>
</div>
<div class="cap-tabs-panel" role="tabpanel" id="tlp-draft" aria-labelledby="tl-draft" tabindex="0">
<p>Why the spring survey keeps growing. Last saved 13:58.</p>
</div>
<div class="cap-tabs-panel" role="tabpanel" id="tlp-preview" aria-labelledby="tl-preview" tabindex="0" hidden>
<p>The post as readers will see it, at the width of the blog column.</p>
</div>
<div class="cap-tabs-panel" role="tabpanel" id="tlp-history" aria-labelledby="tl-history" tabindex="0" hidden>
<p>Seven saved versions, the newest from 13:58 today.</p>
</div>
</div>
Vertical, the tray and the line
<div class="cap-specimen-row">
<div class="cap-tabs" data-cap="tabs" data-orientation="vertical" id="tabs-vertical">
<div class="cap-tabs-list" role="tablist" aria-label="Settings sections" aria-orientation="vertical">
<button type="button" class="cap-tab" role="tab" id="tv-general" aria-selected="true" aria-controls="tvp-general" tabindex="0">General</button>
<button type="button" class="cap-tab" role="tab" id="tv-agents" aria-selected="false" aria-controls="tvp-agents" tabindex="-1">Agents</button>
<button type="button" class="cap-tab" role="tab" id="tv-keys" aria-selected="false" aria-controls="tvp-keys" tabindex="-1">Access keys</button>
</div>
<div class="cap-tabs-panel" role="tabpanel" id="tvp-general" aria-labelledby="tv-general" tabindex="0"><p>Name, region and time zone.</p></div>
<div class="cap-tabs-panel" role="tabpanel" id="tvp-agents" aria-labelledby="tv-agents" tabindex="0" hidden><p>Three agents may write drafts.</p></div>
<div class="cap-tabs-panel" role="tabpanel" id="tvp-keys" aria-labelledby="tv-keys" tabindex="0" hidden><p>Two keys, last used yesterday.</p></div>
</div>
<div class="cap-tabs" data-cap="tabs" data-orientation="vertical" id="tabs-vertical-line">
<div class="cap-tabs-list" role="tablist" aria-label="Report sections" aria-orientation="vertical" data-variant="line">
<button type="button" class="cap-tab" role="tab" id="tw-uptime" aria-selected="true" aria-controls="twp-uptime" tabindex="0">Uptime</button>
<button type="button" class="cap-tab" role="tab" id="tw-latency" aria-selected="false" aria-controls="twp-latency" tabindex="-1">Latency</button>
<button type="button" class="cap-tab" role="tab" id="tw-errors" aria-selected="false" aria-controls="twp-errors" tabindex="-1">Errors</button>
</div>
<div class="cap-tabs-panel" role="tabpanel" id="twp-uptime" aria-labelledby="tw-uptime" tabindex="0"><p>99.94 percent over 30 days.</p></div>
<div class="cap-tabs-panel" role="tabpanel" id="twp-latency" aria-labelledby="tw-latency" tabindex="0" hidden><p>Median 212 ms, slowest 1.4 s.</p></div>
<div class="cap-tabs-panel" role="tabpanel" id="twp-errors" aria-labelledby="tw-errors" tabindex="0" hidden><p>Eleven failed checks, all on September 28.</p></div>
</div>
</div>
Manual activation: arrows move focus, Enter or Space chooses
<div class="cap-tabs" data-cap="tabs" data-activation="manual" id="tabs-manual">
<div class="cap-tabs-list" role="tablist" aria-label="Exports">
<button type="button" class="cap-tab" role="tab" id="tm-posts" aria-selected="true" aria-controls="tmp-posts" tabindex="0">Posts</button>
<button type="button" class="cap-tab" role="tab" id="tm-media" aria-selected="false" aria-controls="tmp-media" tabindex="-1">Media</button>
<button type="button" class="cap-tab" role="tab" id="tm-mentions" aria-selected="false" aria-controls="tmp-mentions" tabindex="-1">Mentions</button>
</div>
<div class="cap-tabs-panel" role="tabpanel" id="tmp-posts" aria-labelledby="tm-posts" tabindex="0"><p>Export 312 posts as Markdown.</p></div>
<div class="cap-tabs-panel" role="tabpanel" id="tmp-media" aria-labelledby="tm-media" tabindex="0" hidden><p>Export 1,204 images and documents, about 3.1 GB.</p></div>
<div class="cap-tabs-panel" role="tabpanel" id="tmp-mentions" aria-labelledby="tm-mentions" tabindex="0" hidden><p>Export 86 mentions as CSV.</p></div>
</div>
The address follows the tab (data-sync="hash")
<div class="cap-tabs" data-cap="tabs" data-sync="hash" id="tabs-hash">
<div class="cap-tabs-list" role="tablist" aria-label="Help topics" data-variant="line">
<button type="button" class="cap-tab" role="tab" id="th-start" aria-selected="true" aria-controls="thp-start" tabindex="0">Getting started</button>
<button type="button" class="cap-tab" role="tab" id="th-keys" aria-selected="false" aria-controls="thp-keys" tabindex="-1">Keyboard</button>
</div>
<div class="cap-tabs-panel" role="tabpanel" id="thp-start" aria-labelledby="th-start" tabindex="0"><p>Add a site, then a check.</p></div>
<div class="cap-tabs-panel" role="tabpanel" id="thp-keys" aria-labelledby="th-keys" tabindex="0" hidden><p>Press ? for every shortcut.</p></div>
</div>
Links: tabs that are pages, the current one marked
<div class="cap-specimen-row">
<nav class="cap-tabs-list" aria-label="Filter mentions by status" id="tabs-links">
<a class="cap-tab" href="#open" aria-current="page">Open<span class="cap-tab-count">12</span></a>
<a class="cap-tab" href="#resolved">Resolved<span class="cap-tab-count">48</span></a>
<a class="cap-tab" href="#all">All<span class="cap-tab-count">60</span></a>
</nav>
</div>
<div class="cap-specimen-row">
<nav class="cap-tabs-list" data-variant="line" aria-label="Filter posts by status" id="tabs-links-line">
<a class="cap-tab" href="#all-posts">All<span class="cap-tab-count">312</span></a>
<a class="cap-tab" href="#published" aria-current="page">Published<span class="cap-tab-count">287</span></a>
<a class="cap-tab" href="#drafts">Drafts<span class="cap-tab-count">21</span></a>
<a class="cap-tab" href="#scheduled">Scheduled<span class="cap-tab-count">4</span></a>
</nav>
</div>
Links drawn by an app's router: the nav's link slot
<div data-mount="router"></div>
The same, with the slot on each link
<div data-mount="router-per-link"></div>
In a narrow space the list scrolls, nothing is clipped
<div class="tabs-narrow-box" id="tabs-narrow-box">
<div class="cap-tabs" data-cap="tabs" id="tabs-narrow">
<div class="cap-tabs-list" role="tablist" aria-label="Collections">
<button type="button" class="cap-tab" role="tab" id="tn-posts" aria-selected="true" aria-controls="tnp-posts" tabindex="0">Posts</button>
<button type="button" class="cap-tab" role="tab" id="tn-procedures" aria-selected="false" aria-controls="tnp-procedures" tabindex="-1">Procedures</button>
<button type="button" class="cap-tab" role="tab" id="tn-mentions" aria-selected="false" aria-controls="tnp-mentions" tabindex="-1">Mentions</button>
<button type="button" class="cap-tab" role="tab" id="tn-media" aria-selected="false" aria-controls="tnp-media" tabindex="-1">Media library</button>
</div>
<div class="cap-tabs-panel" role="tabpanel" id="tnp-posts" aria-labelledby="tn-posts" tabindex="0"><p>312 posts.</p></div>
<div class="cap-tabs-panel" role="tabpanel" id="tnp-procedures" aria-labelledby="tn-procedures" tabindex="0" hidden><p>18 procedures.</p></div>
<div class="cap-tabs-panel" role="tabpanel" id="tnp-mentions" aria-labelledby="tn-mentions" tabindex="0" hidden><p>86 mentions.</p></div>
<div class="cap-tabs-panel" role="tabpanel" id="tnp-media" aria-labelledby="tn-media" tabindex="0" hidden><p>1,204 files.</p></div>
</div>
</div>
Comfortable density
<div data-density="comfortable">
<div class="cap-tabs" data-cap="tabs" id="tabs-comfortable">
<div class="cap-tabs-list" role="tablist" aria-label="Density sample">
<button type="button" class="cap-tab" role="tab" id="tc-a" aria-selected="true" aria-controls="tcp-a" tabindex="0">Overview</button>
<button type="button" class="cap-tab" role="tab" id="tc-b" aria-selected="false" aria-controls="tcp-b" tabindex="-1">Runs</button>
</div>
<div class="cap-tabs-panel" role="tabpanel" id="tcp-a" aria-labelledby="tc-a" tabindex="0"><p>Roomier tabs.</p></div>
<div class="cap-tabs-panel" role="tabpanel" id="tcp-b" aria-labelledby="tc-b" tabindex="0" hidden><p>Runs.</p></div>
</div>
</div>
Pill variant: drag the pill, or click, or use the arrows; each tab its own tone; the panels inside a layout
<div class="cap-tabs" data-cap="tabs" id="tabs-pill">
<div class="cap-tabs-list" role="tablist" aria-label="Markup view" data-variant="pill">
<button type="button" class="cap-tab" role="tab" id="tp-original" aria-selected="false" aria-controls="tpp-original" tabindex="-1" data-tone="info">Original</button>
<button type="button" class="cap-tab" role="tab" id="tp-simple" aria-selected="true" aria-controls="tpp-simple" tabindex="0" data-tone="ok">Simple markup</button>
<button type="button" class="cap-tab" role="tab" id="tp-all" aria-selected="false" aria-controls="tpp-all" tabindex="-1" data-tone="warn">All markup</button>
</div>
<div class="cap-specimen-row">
<div class="cap-tabs-panel" role="tabpanel" id="tpp-original" aria-labelledby="tp-original" tabindex="0" hidden><p>The draft as Alex Rivera sent it, with no changes shown.</p></div>
<div class="cap-tabs-panel" role="tabpanel" id="tpp-simple" aria-labelledby="tp-simple" tabindex="0"><p>Changes marked in the margin; the text reads as edited.</p></div>
<div class="cap-tabs-panel" role="tabpanel" id="tpp-all" aria-labelledby="tp-all" tabindex="0" hidden><p>Every insertion and deletion inline, with Sam Lee's comments.</p></div>
</div>
</div>
Pill variant in a site's own look: tabs of one width (--cap-tab-min-inline-size), the chosen label in the accent (--cap-tab-ink)
<div class="cap-tabs" data-cap="tabs" id="tabs-pill-own">
<div class="cap-tabs-list tabs-own-look" role="tablist" aria-label="Draft view" data-variant="pill">
<button type="button" class="cap-tab" role="tab" id="to-draft" aria-selected="true" aria-controls="top-draft" tabindex="0">Draft</button>
<button type="button" class="cap-tab" role="tab" id="to-notes" aria-selected="false" aria-controls="top-notes" tabindex="-1">Notes</button>
</div>
<div class="cap-tabs-panel" role="tabpanel" id="top-draft" aria-labelledby="to-draft" tabindex="0"><p>The draft Jordan Park is editing.</p></div>
<div class="cap-tabs-panel" role="tabpanel" id="top-notes" aria-labelledby="to-notes" tabindex="0" hidden><p>Two notes from Sam Lee.</p></div>
</div>
Progressive and remembered: links to every panel until script runs; the reader's choice kept for every set
<div class="cap-tabs" data-cap="tabs" data-progressive data-remember="specimen-platform" data-remember-guess="platform" id="tabs-progressive">
<div class="cap-tabs-list" data-variant="line" data-label="Platform">
<a class="cap-tab" href="#tg-install-macos" data-value="macos">macOS</a>
<a class="cap-tab" href="#tg-install-windows" data-value="windows">Windows</a>
<a class="cap-tab" href="#tg-install-linux" data-value="linux">Linux</a>
</div>
<div class="cap-tabs-panel" id="tg-install-macos"><p class="cap-tabs-panel-label">macOS</p><pre><code>brew install example-cli</code></pre></div>
<div class="cap-tabs-panel" id="tg-install-windows"><p class="cap-tabs-panel-label">Windows</p><pre><code>winget install Example.Cli</code></pre></div>
<div class="cap-tabs-panel" id="tg-install-linux"><p class="cap-tabs-panel-label">Linux</p><pre><code>sudo apt install example-cli</code></pre></div>
</div>
<div class="cap-tabs" data-cap="tabs" data-progressive data-remember="specimen-platform" data-remember-guess="platform" id="tabs-progressive-2">
<div class="cap-tabs-list" data-variant="line" data-label="Platform">
<a class="cap-tab" href="#tg-run-macos" data-value="macos">macOS</a>
<a class="cap-tab" href="#tg-run-windows" data-value="windows">Windows</a>
<a class="cap-tab" href="#tg-run-linux" data-value="linux">Linux</a>
</div>
<div class="cap-tabs-panel" id="tg-run-macos"><p class="cap-tabs-panel-label">macOS</p><pre><code>example-cli start --open</code></pre></div>
<div class="cap-tabs-panel" id="tg-run-windows"><p class="cap-tabs-panel-label">Windows</p><pre><code>example-cli.exe start --open</code></pre></div>
<div class="cap-tabs-panel" id="tg-run-linux"><p class="cap-tabs-panel-label">Linux</p><pre><code>example-cli start --open</code></pre></div>
</div>
Page tabs: each tab the page's address with ?tab=, other parameters kept
<div data-mount="page-tabs"></div>
API reference
Tabs
| Prop | Type | Required | Does |
|---|---|---|---|
value | string | Controlled: the chosen tab, with onValueChange. Or uncontrolled: defaultValue. | |
defaultValue | string | ||
onValueChange | (value: string) => void | ||
orientation | Orientation | ||
activation | Activation | "automatic" (default): an arrow key chooses the tab it lands on. "manual": it only moves focus, and Enter or Space chooses (for panels that are slow to show). | |
remember | string | Remembers the reader's choice on this device under this key, and follows a choice made in any other tab set with the same key (tabs.ts, readRemembered). Read after hydration, so the server's tab paints first. rememberGuess="platform" starts from the reader's system when nothing is kept. | |
rememberGuess | "platform" |
And every attribute of <element>.
TabsList
| Prop | Type | Required | Does |
|---|---|---|---|
aria-label | string | Yes | The list needs a name: "Posts", "Settings sections". |
variant | "default" | "line" | "pill" | "pill": a rounded tray whose mark a pointer can drag from tab to tab (tabs.ts, attachPillDrag). | |
size | "sm" | "default" | "lg" | ||
fill | boolean |
And every attribute of <element>.
TabsTrigger
| Prop | Type | Required | Does |
|---|---|---|---|
value | string | Yes | |
tone | TabTone | The pill variant's mark takes this tone while the tab is chosen (or under a drag). | |
count | number | A number beside the label. The accessible name reads "Open 12". | |
disabled | boolean |
And every attribute of <element>.
TabsContent
| Prop | Type | Required | Does |
|---|---|---|---|
value | string | Yes |
And every attribute of <element>.
TabsNav
| Prop | Type | Required | Does |
|---|---|---|---|
aria-label | string | Yes | |
variant | "default" | "line" | "pill" | ||
size | "sm" | "default" | "lg" | ||
fill | boolean | ||
renderLink | RenderTabLink | The link slot for every TabLink inside: how an app's router draws a link (a client-side navigation), so a tab link is a router link and still carries the tab's look and state. |
And every attribute of <element>.
TabLink
| Prop | Type | Required | Does |
|---|---|---|---|
href | string | Yes | |
current | boolean | ||
count | number | ||
children | ReactNode | Yes | |
renderLink | RenderTabLink | This link only: how the router draws it. Wins over the nav's renderLink. |
And every attribute of <anchor>.
PageTabs
| Prop | Type | Required | Does |
|---|---|---|---|
path | string | Yes | The page's path, without the query: "/agents". |
search | string | The address's query as the router has it ("?q=draft" or "q=draft"): kept on every tab. | |
tabs | ReadonlyArray<PageTab> | Yes | |
current | string | Yes | The id of the tab the address names. |
param | string | The query parameter: "tab" by default. | |
aria-label | string | Yes | |
variant | "default" | "line" | "pill" | ||
size | "sm" | "default" | "lg" | ||
fill | boolean | ||
renderLink | RenderTabLink | The link slot for every TabLink inside: how an app's router draws a link (a client-side navigation), so a tab link is a router link and still carries the tab's look and state. |
And every attribute of <element>.
Functions
| Function | Signature | Does |
|---|---|---|
readRemembered | (key: string): string | null | |
writeRemembered | (key: string, value: string): void | Keeps a choice; every tab set remembering the same key follows it. |
onRemembered | (key: string, fn: (value: string) => void): () => void | Calls back with each new choice made for key, on this page or in another window. |
guessPlatform | (ua?: string): "ios" | "android" | "windows" | "macos" | "linux" | null | The reader's system from the browser's report: "ios", "android", "windows", "macos" or "linux", or null when it says none of those. Phones first: an iPhone says "like Mac OS X" and Android says "Linux". data-remember-guess="platform" picks the tab whose value it is; web-push names a device with it. |
tabValue | (tab: HTMLElement): string | A tab's value: its data-value, else the id of the panel it controls. |
tabParam | (search: string, param?: string): string | null | Page tabs (PageTabs, or links written by hand): each tab is the page's address with ?tab=<id>, the first tab the bare address, other query parameters kept. The ?tab= value an address's query names, or null. |
pageTabHref | (path: string, search: string, id: string, firstId: string | undefined, param?: string): string | The address of a page tab: path with search's other parameters and ?tab=id (none for the first tab). |
setPanelHidden | (panel: HTMLElement, hide: boolean): void | Shows a panel, or hides it in the way this browser can still search (not the panel of a disabled tab). |
nextTab | (enabled: number[], current: number, key: string, orientation?: Orientation, rtl?: boolean): number | null | The tab to move to for a key, among the tabs that can be chosen. enabled holds the positions of the tabs not disabled, in order; current is the position of the focused tab. Left and Right move a horizontal list (swapped in a right-to-left page), Up and Down a vertical one; Home and End go to the ends; the ends wrap. Returns the position to focus, or null when the key is not one of these. |
tabsOf | (root: HTMLElement): HTMLElement[] | This tab set's own tabs and panels (not those of a tab set nested in a panel). |
panelsOf | (root: HTMLElement): HTMLElement[] | A panel is a child of the set, or deeper in it when a layout wraps the panels (a column beside them), so long as no tab set nested inside holds it. |
panelOf | (root: HTMLElement, tab: HTMLElement): HTMLElement | null | |
select | (root: HTMLElement, tab: HTMLElement, options?: { focus?: boolean | undefined; silent?: boolean | undefined; }): boolean | Chooses a tab: it becomes the one tab stop, its panel shows, the others hide. A disabled tab is not chosen. Tells the page with a cap:tabs-change event (bubbles) carrying the tab and its panel. Returns whether the tab was chosen. |
upgrade | (root: HTMLElement): boolean | Progressive tabs (data-progressive on .cap-tabs): the server sends the list as links to the panels (href="#id") and every panel showing, each under its own name (.cap-tabs-panel-label), which is the whole page with script off, on paper and for a machine. This turns the links into tabs: the list a tablist (named by its aria-label, or its data-label), each link a tab, each panel a tabpanel, one panel showing. Returns whether the set is tabs now. |
attachPillDrag | (list: HTMLElement, pick: (tab: HTMLElement) => void): () => void | The pill variant's mark follows a drag (data-variant="pill", a horizontal list): press anywhere on the list and slide, and the mark moves with the pointer, held between the first and last tab; let go and the tab nearest the mark is chosen through pick, and the mark settles on it. A press that does not move is a click, as on any tab. The mark's place while dragging goes through the CSSOM (--cap-pill-start, --cap-pill-end); the tab under it carries data-near. |
enhance | (root?: Element | Document): () => void | Attaches every [data-cap="tabs"] under root not yet attached. Returns a function that detaches them. Document | Element, not ParentNode: under the Workers types an HTMLElement is not a ParentNode (their Element's append differs), so enhance(root) failed to typecheck in bsw. |
CSS variables
| Variable | Default |
|---|---|
--_soft | var(--cap-tab-mark, var(--surface)) |
--_tone | var(--accent) |
--cap-pill-end | set by the page |
--cap-pill-start | set by the page |
--cap-tab-fs | var(--fs-body) |
--cap-tab-h | max(var(--target), calc(var(--control) - 6px)) |
--cap-tab-ink | var(--text) |
--cap-tab-mark | var(--surface) |
--cap-tab-mark-edge | var(--_tone) |
--cap-tab-mark-radius | var(--radius-full) |
--cap-tab-mark-shadow | var(--shadow-xs) |
--cap-tab-min-inline-size | var(--target) |
--cap-tab-tone | var(--_tone) |
--cap-tab-weight | var(--weight-medium) |
--cap-tabs-tray | var(--sunken) |
--cap-tabs-tray-radius | var(--radius-full) |
Parts and data attributes
| Class | Is |
|---|---|
.cap-tab | its own class |
.cap-tab-count | its own class |
.cap-tabs | the root |
.cap-tabs-list | a part |
.cap-tabs-panel | a part |
.cap-tabs-panel-label | a part |
| Attribute | Values |
|---|---|
data-dragging | present or absent |
data-fill | present or absent |
data-near | present or absent |
data-orientation | vertical |
data-progressive | present or absent |
data-size | lg sm |
data-tone | accent crit info ok warn |
data-variant | line pill |
| State | Read from |
|---|---|
:disabled | the platform |
:focus-visible | the platform |
:hover | the platform |
:visited | the platform |
[aria-current="page"] | an attribute |
[aria-disabled="true"] | an attribute |
[aria-selected="true"] | an attribute |
[hidden="until-found"] | an attribute |
[hidden] | an attribute |
Accessibility
| Key | Does |
|---|---|
| Tab | Enters the list on the chosen tab, then moves on to the panel |
| Right arrow, Left arrow | Moves to the next or previous tab and, with automatic activation, chooses it. At the ends it wraps. Down and Up in a vertical list. In a right-to-left page the arrows swap |
| Home, End | First or last tab |
| Enter, Space | Chooses the focused tab (manual activation) |
| Key | Does |
|---|---|
| Tab | Each link is a tab stop |
| Enter | Follows the link |
Panels:
A disabled tab is skipped by every key above. Progressive tabs and the pill take the same keys. The pill's drag is for a pointer only and is never the only way to choose.
Links (and page tabs):
- Panels:
role="tablist"named byaria-label,role="tab"witharia-selectedandaria-controls,role="tabpanel"witharia-labelledby. A rovingtabindex: the chosen tab is 0, the rest -1. A vertical list also hasaria-orientation="vertical". A panel hastabindex="0", so a person who tabs past the list lands on its content even when it holds nothing focusable. - Links: a
navnamed byaria-label, the current linkaria-current="page". No tab roles: they are links. - Progressive: before script, links to the panels (in-page links, each panel under its own visible name); after, the full tab roles above, the list named by its
data-label(oraria-label). The links keep theirhref; a click chooses the tab and does not jump the page. - Pill: the drag is a pointer's extra (WCAG 2.5.7): a click and the arrow keys choose every tab. The chosen tab is still marked by its edge and weight, not by the tone alone.
- A disabled tab has
aria-disabled="true". It is not removed from the page. - Contrast: tab text 4.5:1 on the tray and on the raised tab; the chosen tab's edge and the line variant's rule 3:1.
- Hit areas are at least
var(--target); forced colors draw the chosen tab in Highlight.