Tabs

The strip renders from the options array; each <TabPanel> renders a self-managing <a-tabpanel>. Tabs never reads or toggles the panels: there’s no child introspection, so it renders the same in static SSR and works with any renderer. There is no wrapper element: the JSX becomes the strip followed by the panels as flat siblings, and className / id / style / ...rest land on the strip. Arranging them is up to you (see below):

<a-tabs role="tablist">
  <a-tab role="tab" value="account" tabindex="0"><a-tab-label>Account</a-tab-label></a-tab>
  …
</a-tabs>
<a-tabpanel role="tabpanel" value="account">…</a-tabpanel>   <!-- active: shown -->
<a-tabpanel role="tabpanel" value="security">…</a-tabpanel>  <!-- inactive: display:none -->

A horizontal strip stacks above its panels in normal flow with no extra markup; for a vertical strip beside its panels, wrap <Tabs> in your own flex row. The panels find the strip as a sibling under the same parent (a-tabpanel → :scope > a-tabs), so keep them together; to split them into separate layout regions, drive a controlled value and render the panels yourself.

Each <a-tabpanel> sits beside <a-tabs> (its sibling, never inside it, so a panel never lands in the primary track). It reads the active value from <a-tabs> and shows/hides itself via its own off-DOM :state(active); nothing writes hidden / inert on it. The panel↔tab link is off-DOM too (internals.ariaLabelledByElements), so no id wiring is needed. No web component writes the light DOM, only your JSX does, which keeps a worker-thread reactive engine in sync.

A <TabPanel> stays mounted while inactive (its DOM, form values, and scroll survive tab switches); hideMode picks how it hides:

• display (default): display:none; leaves the tab order + a11y tree.
• visibility: visibility:hidden, keeping its layout box (to avoid reflow or to measure a hidden panel).

<TabPanel value="b" hideMode="visibility"><Chart /></TabPanel>

To not render an inactive panel at all (unmount it to reset its state or defer an expensive subtree, or mount it lazily on first open), drive selection with a controlled value and render the panels yourself. Tabs passes panels straight through, so you decide what’s mounted:

const [tab, setTab] = useState('a')

// Unmount inactive — only the open panel exists:
<Tabs value={tab} onStateChange={(_e, { next }) => next && setTab(next)} options={…}>
  {tab === 'a' && <TabPanel value="a"><Expensive /></TabPanel>}
  {tab === 'b' && <TabPanel value="b"><Form /></TabPanel>}
</Tabs>

// Lazy — mount on first open, keep after (track a "seen" set in state):
{seen.has('b') && <TabPanel value="b"><Heavy /></TabPanel>}

The same controlled pattern places the strip and panels in different layout regions: render <Tabs options={…} value onStateChange> in one place and your content wherever you like, switching on the value yourself.

The selected tab is in the page’s tab order. Once focus enters the strip, the arrow keys move between enabled tabs (wrapping at the ends), Home / End jump to the first / last, and Space / Enter activate the focused tab; arrow / Home / End navigation activates as it moves (selection follows focus). Disabled tabs are skipped and dropped from the tab order.

Pass label for the tablist’s accessible name. Each <TabPanel> names its tab as its accessible label (aria-labelledby), set off-DOM so nothing writes the panel’s attributes. Static panel content remains readable without making the panel a tab stop. Set tabIndex={0} when you want a text-only panel itself to receive focus; when the panel starts with a focusable control, Tab reaches that control directly.

Tabs reports the picked value and leaves navigation to the app, so a strip can switch routes as readily as panels. Treat each value as a path: control value from the current location and navigate in onStateChange (the pick fires on click; onValueChange waits for value to change, which for a route happens only after you’ve already navigated). Skip the <TabPanel>s, since the router renders the view.

<Tabs
  value={pathname}
  onStateChange={(_e, { next }) => next && navigation.navigate(next)}
  options={[
    { value: '/settings/profile', label: 'Profile' },
    { value: '/settings/billing', label: 'Billing' },
  ]}
/>

Swap navigation.navigate for whatever the app uses (router.push, Astro’s navigate, location.assign). Controlling value from the route keeps the right tab active through back/forward and deep links. To guard a switch (unsaved edits), veto it in onStateChange with event.preventDefault().

Use the web component directly when you are not using React or Preact and a native control does not fit.

Keep the tab strip and panels as siblings under one parent. Panels read the active value from <a-tabs>. Give the selected tab tabindex="0" and the others tabindex="-1"; <a-tabs> moves focus and selection with the arrow keys, while your change handler updates those attributes for the next visit to the strip. Add tabindex="0" to a text-only panel only when you want the panel itself in the page Tab sequence.

Add fill to make horizontal tabs share the available width equally.

<div>
  <a-tabs role="tablist" default-state="account" fill>
    <a-tab role="tab" value="account" tabindex="0"><a-tab-label>Account</a-tab-label></a-tab>
    <a-tab role="tab" value="security" tabindex="-1"><a-tab-label>Security</a-tab-label></a-tab>
  </a-tabs>
  <a-tabpanel role="tabpanel" value="account">Account settings</a-tabpanel>
  <a-tabpanel role="tabpanel" value="security">Security settings</a-tabpanel>
</div>

const tabs = document.querySelector('a-tabs')

tabs.addEventListener('change', () => {
  for (const tab of tabs.querySelectorAll('a-tab')) {
    tab.tabIndex = tab.getAttribute('value') === tabs.value ? 0 : -1
  }
})

Reach for the props first: tone, size, priority. The focus ring is the global --focus-ring (see Colors).

For anything else the strip is light-DOM: <a-tabs> the tablist, each <a-tab> a tab (its text wrapped in <a-tab-label>), <a-tabpanel> a panel, and the moving indicator is <a-tabs>’s ::before. Target them with ordinary CSS (an un-layered rule beats @layer anta without !important) and reach for real properties (border-radius, padding, background, …), not the internal --* output tokens. The demo classes (.square-tabs, .glow-tabs, …) are hooks. Replace them with selectors you own.

Roomier track. The strip hugs its tabs by default (0 padding), so it’s exactly a same-size button tall. For a gap around the selected pill (the classic “well” look), add padding and bump border-radius by the same amount, so the outer corner stays concentric with the tabs’ 4px. The strip grows 2×the padding taller.

a-tabs.roomy-1 { padding: 1px; border-radius: 5px; }   /* 4 + 1 */
a-tabs.roomy-3 { padding: 3px; border-radius: 7px; }   /* 4 + 3 */

Squarer primary. Square corners, heavier labels, and a roomier 4px track with no border or ring on the strip (box-shadow: none drops the default track ring) — just a 1px square ring on the raised pill. The track is <a-tabs>, the sliding pill its ::before:

a-tabs.square-tabs         { border-radius: 0; padding: 4px; box-shadow: none; }  /* no track border / ring */
.square-tabs a-tab         { border-radius: 0; font-weight: 600; }
a-tabs.square-tabs::before { border-radius: 0; box-shadow: 0 0 0 1px light-dark(#cfcfd6, #46464e); }  /* 1px square pill ring */

Tertiary glowing underline. Recolor the sliding underline and add a radial highlight rising from it. The slider is a full-cover box whose border-bottom is the line, so a background gradient on it fills the tab behind the label. Because it’s one element, the glow slides with the line between tabs, with no noslide and no separate per-tab background.

/* The class is on the <a-tabs> element itself, so target a-tabs.glow-tabs (not a descendant).
   The tertiary slider is a full-cover box with a border-bottom line — recolor the border and
   fill it with a gradient; both slide together. Where CSS anchor positioning isn't supported
   there's no slider — tertiary falls back to the per-tab ::after underline (a plain line). */
a-tabs.glow-tabs::before {
  border-bottom-color: light-dark(#8067ff, #907aff);   /* recolor the sliding line */
  background:                                          /* highlight rising from the line, slides with it */
    radial-gradient(80% 100% at 50% 100%,
      color-mix(in oklch, light-dark(#8067ff, #907aff) 30%, transparent), transparent 70%);
}

Scroll instead of ellipsizing. Keep full labels and let the strip scroll horizontally: pin each tab to its content width (flex: none) and make the strip scrollable.

.scroll-tabs a-tabs { overflow-x: auto; scrollbar-width: thin; }
.scroll-tabs a-tab  { flex: none; }

Equal-width tabs. By default tabs are sized to their labels (and compress only when the strip overflows). Pass fill for a segmented-control look where every tab shares the strip width:

<Tabs
  fill
  defaultValue="all"
  label="Filter"
  options={[
    { value: 'all', label: 'All' },
    { value: 'assigned', label: 'Assigned to me' },
    { value: 'recent', label: 'Recent' },
    { value: 'archived', label: 'Archived' },
  ]}
/>

Wrap labels. Let long labels wrap so the tabs grow taller instead of truncating:

.wrap-tabs a-tab,
.wrap-tabs a-tab-label { white-space: normal; text-overflow: clip; overflow: visible; text-align: center; }

Disable the slide. By default the selected-tab indicator slides between tabs (a single rectangle, via CSS anchor positioning). Pass noslide to paint it on each tab instead, so the highlight snaps with no movement. It’s also the automatic fallback where anchor positioning isn’t supported.

<Tabs noslide defaultValue="a">…</Tabs>

Fully-rounded pill. The built-in round prop rounds the track, every tab, and the sliding pill to 999px in one flag, no CSS needed (it drives --tab-radius, which feeds the tabs, the moving indicator, and the primary track well):

<Tabs round defaultValue="a" label="Sections">…</Tabs>   {/* pill track + tabs + indicator */}