Primitives
Headless, progressively enhanced behaviour for design system components.
Install them with pnpm add @govuk-react/primitives. You don't need them to use govuk-react, which already includes them.
Headless behaviour for design system components, as light-DOM custom elements with unstyled React parts over them. It sets no look and ships no GOV.UK markup, so any library can use it. govuk-react’s components are the reference implementation, built with govuk-frontend-react’s markup.
Each primitive:
- works without JavaScript, through a fallback you choose
- upgrades to the full WAI-ARIA pattern when its custom element is defined, with or without React
- adds React props for its state once hydrated, where it has any, such as
valueandonValueChange, oropenandonOpenChange - takes
asChildon its parts, so you render your own elements. ARootis the custom element, except Button’s - names its parts and props alike: the control that operates it is
Trigger, and a text prop ends inTextwhen it’s shown,Labelwhen it’s an accessible name andAnnouncementwhen only screen readers hear it
Import each primitive from its own path, such as @govuk-react/primitives/tabs. Each path defines its element when imported.
Controlled state
Prefer uncontrolled: leave out value and open, start from defaultValue or defaultOpen where there is one, and listen with onValueChange or onOpenChange. The markup then holds the state, so it’s the same before hydration, without React and without JavaScript.
Control a primitive only when your app has to set its state, such as closing a menu after navigating. When controlled, a user’s action calls the change handler and the primitive changes only when the prop does. That has limits that can’t be removed:
- A controlled prop applies once React has hydrated. Until then the primitive is uncontrolled, so it still works, and what the user did by then is reported through the change handler rather than undone. If your handler doesn’t adopt it, the primitive goes back to the prop.
- Without JavaScript, a controlled prop does nothing.
- Each change waits for React to render, where an uncontrolled one happens in the browser straight away.
- A browser doesn’t let a page cancel a script calling
close()on a dialog, nor a script callingshowModal()before it firedbeforetoggleon dialogs (Chrome 132, Firefox 133 and Safari 26). A controlled Modal reports such a change throughonOpenChangeand, unlessopenchanges within 100ms, puts the dialog back asopensays. So it always ends up matchingopen, but the user can see it change and change back.
Changes made before hydration
onValueChange and onOpenChange on Tabs, Accordion, Disclosure and Modal get a second argument, { beforeHydration }. It’s true for a change the user made before React hydrated, which is reported once React has hydrated, whether or not the primitive is controlled.
Such a report differs from a live change:
- It’s the state the user left, not each step. Three tabs picked before hydration are reported as one change, to the last.
- It doesn’t happen as the user acts, so a handler that navigates, fetches or logs runs at hydration.
- Several primitives report in the order React runs their effects, not the order the user used them.
So where one primitive’s handler changes another’s state, or has side effects, check the argument and decide what a late report should do:
<Tabs.Root
value={tab}
onValueChange={(value, { beforeHydration }) => {
if (beforeHydration) return;
setTab(value);
}}
>
Returning without changing value puts the tabs back to value.
Styles
Two fallbacks need a CSS rule each, which only set display: the Tabs radios fallback and the Accordion. Load the package’s stylesheet once, or copy its rules into your own:
import '@govuk-react/primitives/styles.css';
No part renders a style element or attribute, so the primitives work under a strict Content Security Policy.
Without React
Each element is also exported on its own, with no React, from @govuk-react/primitives/<name>-element, such as tabs-element. Importing it defines the element, such as <govuk-react-tabs>. Render the same markup as the React parts do: the element finds its parts by data- attributes, takes its options as attributes, and reports changes with bubbling events named after it, such as govuk-react-tabs:change. The comment at the top of each element’s source lists its markup, attributes and events:
accordion, auto-focus, autocomplete, button, character-count, choices, disclosure, exit-this-page, file-upload, focus-links, modal, password-input and tabs.
Each element that changes how its markup shows sets data-upgraded on itself once upgraded, to style it apart from its fallback.
Inline scripts
Each element is also built as a small, self-contained classic script, with no imports and no React, at @govuk-react/primitives/inline/<name>-element.js, such as inline/tabs-element.js. Inline the ones your page uses, so the markup is interactive as soon as it loads, before React has downloaded and hydrated. React’s parts then pick up from the elements, including anything the user did before hydration. Each element is defined only once, whichever runs first: the inline script or React’s bundle. So inline the scripts from the same version of this package as the one in your bundle.
To render them from React on the server, inline-script has each script as a string, and an InlineScript component:
import { InlineScript, tabs } from '@govuk-react/primitives/inline-script';
<head>
<InlineScript script={tabs} nonce={nonce} />
</head>;
The scripts are accordion, autocomplete, autoFocus, button, characterCount, choices, disclosure, exitThisPage, fileUpload, focusLinks, modal, passwordInput and tabs. InlineScript isn’t a client component, so the scripts stay out of client bundles. A script React adds in the browser doesn’t run, and isn’t needed, since React’s parts define their elements.