Skip to main content
Primitives

Tabs

Tabs whose hidden radios are the source of truth, with or without JavaScript.

Used by govuk-react's tabs.

Unstyled

The primitive on plain elements, with no GOV.UK markup or styles: what you start from in your own library.

Default

Code
<Tabs.Root defaultValue="past-day">
  <Tabs.List>
    <Tabs.Trigger value="past-day">Past day</Tabs.Trigger>
    <Tabs.Trigger value="past-week">Past week</Tabs.Trigger>
    <Tabs.Trigger value="past-month">Past month</Tabs.Trigger>
  </Tabs.List>
  <Tabs.Content value="past-day">
    <h2>Past day</h2>
    <p>3 cases opened, 0 cases closed.</p>
  </Tabs.Content>
  <Tabs.Content value="past-week">
    <h2>Past week</h2>
    <p>24 cases opened, 18 cases closed.</p>
  </Tabs.Content>
  <Tabs.Content value="past-month">
    <h2>Past month</h2>
    <p>98 cases opened, 95 cases closed.</p>
  </Tabs.Content>
</Tabs.Root>

Radios fallback

Each tab is a label for a hidden radio, so the tabs switch without JavaScript.

Code
<Tabs.RadiosRoot defaultValue="radios-past-day">
  <Tabs.List>
    <Tabs.RadiosTrigger value="radios-past-day">Past day</Tabs.RadiosTrigger>
    <Tabs.RadiosTrigger value="radios-past-week">Past week</Tabs.RadiosTrigger>
  </Tabs.List>
  <Tabs.RadiosContent value="radios-past-day">
    <h2>Past day</h2>
    <p>3 cases opened, 0 cases closed.</p>
  </Tabs.RadiosContent>
  <Tabs.RadiosContent value="radios-past-week">
    <h2>Past week</h2>
    <p>24 cases opened, 18 cases closed.</p>
  </Tabs.RadiosContent>
</Tabs.RadiosRoot>

In govuk-react

govuk-react's tabs, built with this primitive.

Code
<Tabs.Composite items={items} />

Usage

import * as Tabs from '@govuk-react/primitives/tabs';

<Tabs.Root defaultValue="past-day">
  <Tabs.List>
    <Tabs.Trigger value="past-day">Past day</Tabs.Trigger>
    <Tabs.Trigger value="past-week">Past week</Tabs.Trigger>
  </Tabs.List>
  <Tabs.Content value="past-day">…</Tabs.Content>
  <Tabs.Content value="past-week">…</Tabs.Content>
</Tabs.Root>;

Each panel holds a hidden radio, and the radio group is the source of truth, as in the reference. Choosing a tab checks its radio, and the radio’s native change updates the tabs and calls onValueChange.

The root sets how the tabs work without JavaScript, and its parts match it:

  • Root, with Trigger and Content: each tab links to its panel, and every panel shows.
  • RadiosRoot, with RadiosTrigger and RadiosContent: each tab is a label for a hidden radio in its panel, so tabs switch with no JavaScript when clicked. It needs defaultValue or value. Without JavaScript the labels can’t be reached by keyboard, as in the reference. Pass name when tabs render in separate React roots, such as islands. It needs the package’s stylesheet.

They are separate components rather than a prop, because a prop can change after the first render, and the markup each needs can’t.

When controlled with value, a user’s choice calls onValueChange and the tab changes only when value does. value applies once hydrated, so tabs still switch before then, and a tab picked before hydration is reported through onValueChange rather than undone.

orientation ("horizontal" or "vertical") sets the axis of the arrow keys.

media limits the tab behaviour to a media query, and can change. Below it, Root’s tabs are a list of links to panels, and RadiosRoot’s keep switching through their radios. With Root, the URL hash follows the selected tab, as in govuk-frontend.

Each value is also its panel’s id, and its tab links to it, so it must be unique on the page and valid as an id. For another id, pass id to the panel and the matching href to its Trigger.

In an island without a root, pass name and defaultSelected to the triggers and panels. upgradedClass, activeItemClass and hiddenContentClass add classes for styles that key off classes rather than data-state, aria-selected and hidden.

Without React, the markup includes a hidden radio as the first child of each panel.

It follows the Tabs reference in react-design-system-apis.

Inline script

To make the markup interactive before React hydrates, inline @govuk-react/primitives/inline/tabs-element.js, or render it from React on the server:

import { InlineScript, tabs } from '@govuk-react/primitives/inline-script';

<InlineScript script={tabs} nonce={nonce} />;

How inline scripts work

API reference

Tabs.Root

Tabs that are links to every panel without JavaScript. Use Trigger and Content inside it.

PropType
value

The selected tab's value, to control the tabs.

string
defaultValue

The tab selected at first, when uncontrolled. Defaults to the first tab.

string
onValueChange

Called when the user selects a tab.

(value: string, details: ChangeDetails) => void
orientation

The axis of the arrow keys.

"horizontal" | "vertical"
name

The panels' radio group name. Defaults to a generated one.

string
media

Only behave as tabs when this media query matches.

string
upgradedClass

Classes added to the element when it upgrades.

string
activeItemClass

Classes added to the active item.

string
hiddenContentClass

Classes added to inactive panels.

string

Tabs.RadiosRoot

Tabs that switch panels without JavaScript too, through the panels' radios. Use RadiosTrigger and RadiosContent inside it.

PropType
value

The selected tab's value, to control the tabs.

string
defaultValue

The tab selected at first, when uncontrolled. Defaults to the first tab.

string
onValueChange

Called when the user selects a tab.

(value: string, details: ChangeDetails) => void
orientation

The axis of the arrow keys.

"horizontal" | "vertical"
name

The panels' radio group name. Defaults to a generated one.

string
media

Only behave as tabs when this media query matches.

string
upgradedClass

Classes added to the element when it upgrades.

string
activeItemClass

Classes added to the active item.

string
hiddenContentClass

Classes added to inactive panels.

string

Tabs.Content

A panel in a Root. Its id is its value.

PropType
asChild

Render the only child instead, with this part's props merged onto it.

boolean
name

The panels' radio group name.

string
valueRequiredstring
defaultSelected

Whether this panel's radio is checked at first. Defaults to Root's value.

boolean

Tabs.Item

An optional wrapper around a tab, such as a list item.

PropType
asChild

Render the only child instead, with this part's props merged onto it.

boolean
valueRequiredstring

Tabs.List

PropType
asChild

Render the only child instead, with this part's props merged onto it.

boolean

Tabs.RadiosContent

A panel in a RadiosRoot, shown without JavaScript only while its radio is checked. Its id is its value.

PropType
asChild

Render the only child instead, with this part's props merged onto it.

boolean
name

The panels' radio group name.

string
valueRequiredstring
defaultSelected

Whether this panel's radio is checked at first. Defaults to Root's value.

boolean

Tabs.RadiosTrigger

A tab in a RadiosRoot: a label for its panel's radio.

PropType
asChild

Render the only child instead, with this part's props merged onto it.

boolean
valueRequiredstring
name

The panels' radio group name.

string

Tabs.Trigger

A tab in a Root: a link to its panel.

PropType
asChild

Render the only child instead, with this part's props merged onto it.

boolean
valueRequiredstring