How primitives work
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 - reports a state change through
onValueChangeoronOpenChange, with the new state and{ beforeHydration }, rather than a native event such asonToggle. A change the user made before hydration is reported once React hydrates, when there is no event to pass. Native event props still pass through, for changes after hydration - takes
asChildon its parts, so you render your own elements. ARootis the custom element - 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, Details and Modal, and onQueryChange on Autocomplete, 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
Load the package’s stylesheet once, or copy its rules into your own. Its rules only set display:
- Each element gets
display: contents, so it adds no box between your markup and its parent, such as a flex or grid container. The rule has no specificity, so a class of yours that setsdisplayon the element wins, andhiddenstill hides it. - The Tabs radios fallback shows only the checked tab’s panel.
- The Accordion hides its fallback heading once upgraded, and its trigger and controls before then.
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. An attribute sets only where the state starts, such as default-value. To control the state, set a property: value on Tabs and Accordion, which takes an array, and open on Disclosure and Modal. Set it back to undefined or null to stop controlling it. The comment at the top of each element’s source lists its markup, attributes, properties 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 renders only on the server, so the scripts stay out of client bundles: it has no 'use client' directive, and in Astro it needs no client:* directive. A script React adds in the browser doesn’t run, and isn’t needed, since React’s parts define their elements.