Skip to main content
Packages

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} is core, objects, components or utilities, 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 a FormGroup.
  • A block without elements exports a single component named after the block.
  • Modifiers become props of the part.
  • A --hidden modifier becomes a prop that names the visible state instead, such as checked on Radios.Conditional, because hidden is already an HTML attribute.

For example, a class name of govuk-my-block__my-element--my-modifier implies:

  • import { MyBlock } from 'govuk-frontend-react', or import * as MyBlock from 'govuk-frontend-react/my-block'.
  • The block is <MyBlock.Root /> and the element is <MyBlock.MyElement />.
  • <MyBlock.MyElement /> accepts a prop myModifier.

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-l and govuk-heading-m, are a size prop: <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 id to a Field. The hint and error message ids are derived from it, so id={useId()} makes all three unique.
  • Grouped controls, such as Radios.Field and Checkboxes.Field, take idPrefix instead, 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.