govuk-frontend-react
Version 1.0.0-alpha.6. Source on GitHub
govuk-frontend as React components.
This is a direct port: each component renders the same HTML as govuk-frontend’s own Nunjucks macro, and this is checked against every fixture that govuk-frontend publishes. Styles come from govuk-frontend itself. Components are markup only, with no client-side behaviour.
It ports all 39 components of govuk-frontend 6.6.0. More opinionated components, and components govuk-frontend doesn’t provide, belong in govuk-react, which builds on this package.
Install
npm install govuk-frontend-react govuk-frontend react
Requires React 19 or later.
Load govuk-frontend’s styles as its documentation describes, for example:
@use 'govuk-frontend';
Usage
import { Button, StartButton, Fieldset, Label, Hint, ErrorMessageComposite } from 'govuk-frontend-react';
<Fieldset.Root>
<Fieldset.LegendComposite isPageHeading size="l">What is your address?</Fieldset.LegendComposite>
<Label htmlFor="postcode">Postcode</Label>
<Hint id="postcode-hint">For example, SW1A 2AA</Hint>
<ErrorMessageComposite id="postcode-error">Enter a postcode</ErrorMessageComposite>
…
</Fieldset.Root>
<Button variant="secondary">Save as draft</Button>
<StartButton href="/start">Start now</StartButton>
Each component is also its own module:
import * as Fieldset from 'govuk-frontend-react/fieldset';
import { Label } from 'govuk-frontend-react/label';
The package is ES modules only.
Design principles
See docs/design-principles.md, which also lists the API styles each component has.
Conventions
How the design principles apply when rewriting the Nunjucks templates.
BEM
When looking at govuk-frontend BEM class names:
- Blocks become ES modules at
src/{type}/my-block/, where{type}iscore,objects,componentsorutilities, following govuk-frontend’s ITCSS layers. - A block with elements exports each part as a named export, and the package root exports the module as a namespace.
- The part the others sit inside is
Root. Form controls have none, because their outer element is aFormGroup. - A block without elements exports a single component named after the block.
- Modifiers become props of the part.
- A
--hiddenmodifier becomes a prop that names the visible state instead, such ascheckedonRadios.Conditional, becausehiddenis already an HTML attribute.
For example, a class name of govuk-my-block__my-element--my-modifier implies:
import { MyBlock } from 'govuk-frontend-react', orimport * as MyBlock from 'govuk-frontend-react/my-block'.- The block is
<MyBlock.Root />and the element is<MyBlock.MyElement />. <MyBlock.MyElement />accepts a propmyModifier.
So govuk-fieldset__legend--l is <Fieldset.Legend size="l" />, govuk-button--secondary is <Button variant="secondary" />, and govuk-hint is <Hint />. Where a set of modifiers are alternatives, such as sizes or button variants, they share one prop.
BEM convention class name exceptions:
govuk-label-wrapper- Typography sizes, such as
govuk-body-landgovuk-heading-m, are asizeprop:<Body size="l" />,<Heading size="m" />.
Props
Where React prop names differ from the Nunjucks macro option names:
| Nunjucks | React |
|---|---|
element |
as |
attributes |
rest props |
text |
children |
html |
children |
caller |
children |
classes |
className |
govuk-!-width-* |
width on controls and summary list cells |
govuk-!-margin-bottom-* |
marginBottom on Heading, Body and List |
containerClasses |
containerClassName |
describedBy |
aria-describedby |
for |
htmlFor |
isStartButton |
StartButton, which adds the icon |
legend, and others |
a part, such as Fieldset.Legend (see Parts and fields) |
The full mapping for each component is in tests/nunjucks, which the parity tests use to render govuk-frontend’s fixtures through the parts. tests/composite renders them through each Composite and Field, skipping fixtures that use options left to the parts. Both double as a guide for moving from Nunjucks to React.
Parts and fields
Props never take an object that is spread onto another part. Where a Nunjucks macro takes options for a nested element, such as label, hint, errorMessage, formGroup or prefix, the React version is a part you compose:
<FormGroup error>
<Label htmlFor="cost">Cost</Label>
<Hint id="cost-hint">In pounds</Hint>
<ErrorMessageComposite id="cost-error">Enter a cost</ErrorMessageComposite>
<InputWrapper>
<InputPrefix>£</InputPrefix>
<Input id="cost" name="cost" error aria-describedby="cost-hint cost-error" />
</InputWrapper>
</FormGroup>
Form controls also export a Field shorthand, such as InputField, that does what the Nunjucks macro does: it renders the form group, label, hint and error message, and wires up the ids. Its label, hint, errorMessage, prefix and suffix props take content only. labelSize and labelIsPageHeading size the label and make it the page heading, and fieldset-based Fields have legendSize and legendIsPageHeading. Anything else uses the parts.
<InputField name="cost" label="Cost" hint="In pounds" errorMessage="Enter a cost" prefix="£" />
Overriding defaults
Following the first principle, the Field shorthand copies the macro’s id handling, and each piece can be overridden:
- Pass
idto aField. The hint and error message ids are derived from it, soid={useId()}makes all three unique. - Grouped controls, such as
Radios.FieldandCheckboxes.Field, takeidPrefixinstead, as the macro does. - Compose the parts, which derive nothing, for full control over ids and
aria-describedby.
HTML parity
npm run parity renders every govuk-frontend fixture for each ported component and compares it with govuk-frontend’s Nunjucks output. The comparison is on the parsed HTML: attribute order, attribute name case, class order, inline style formatting and formatting whitespace are ignored, but elements, attributes, text and the whitespace between inline content must match. Labels and form controls count as blocks, since govuk-frontend lays them out that way. The parts must match every fixture, unless it’s listed in tests/known-differences.ts with a reason. Each Composite and Field must also match every fixture whose options it supports.
Status
| Component | Fixtures passing |
|---|---|
| Accordion | 13/13 |
| Back link | 7/7 |
| Breadcrumbs | 12/12 |
| Button | 38/38 |
| Character count | 34/34 |
| Checkboxes | 42/42 |
| Cookie banner | 23/23 |
| Date input | 50/50 |
| Details | 10/10 |
| Error message | 9/9 |
| Error summary | 19/19 |
| Exit this page | 4/4 |
| Feedback | 7/7 |
| Fieldset | 18/18 |
| File upload | 22/22 |
| Footer | 25/25 |
| Generic header | 7/7 |
| Header | 6/6 |
| Hint | 6/6 |
| Input | 45/45 |
| Inset text | 6/6 |
| Label | 17/17 |
| Language navigation | 13/13 |
| Notification banner | 21/21 |
| Pagination | 15/15 |
| Panel | 19/19 |
| Password input | 12/12 |
| Phase banner | 7/7 |
| Radios | 43/43 |
| Select | 19/19 |
| Service navigation | 33/33 |
| Skip link | 9/9 |
| Summary list | 30/30 |
| Table | 21/21 |
| Tabs | 14/14 |
| Tag | 12/12 |
| Task list | 11/11 |
| Textarea | 18/18 |
| Warning text | 8/8 |
The page template (Template) and MainWrapper match govuk-frontend’s template.njk, checked in tests/template.test.tsx. React orders <head> itself, and the template’s inline script that adds js-enabled isn’t ported, because it’s client JS.