govuk-frontend-react
Design principles
- A direct markup port. Each component renders the same HTML as govuk-frontend’s macro, even where React developers may expect a different pattern. Anything it derives can be overridden with a prop or by composing the parts.
- Works wherever React renders. No context, state or effects; where the macro derives a value from a parent, a part presets it instead (
Table.RowHeader). Every part renders on its own, so components work on the server, in Server Components, as templates and in separate islands. Opinions and enhancements belong in govuk-react. - Compose parts, don’t configure them. Parts come first, and every multi-part component has a composite, built from them, for basic usage. Props take content, never objects to spread onto a part.
- No govuk classes in your code. Every class govuk-frontend’s macros and fixtures use comes from a part or a prop, including width and margin overrides (
width="one-third",marginBottom={0}). Other override classes come fromoverrideClasses({ fontWeight: 'bold' }). Where a component expects something from another package, such as the logo, it re-exports it as a part with the class applied. - ES modules. ESM only. A component with several parts is a module of named exports (
Fieldset.Legend), never properties on a component. Rootis a component’s outermost part, and only exists when other parts sit inside it. AFieldcomposes a form control inside its form group and fieldset, so itsRoot(if it has one) sits within them. Single-part components are named after themselves.- One component, one folder, with its stories and tests. Styles come from govuk-frontend’s CSS. Stories and JSDoc reuse the GOV.UK Design System’s examples and text and govuk-frontend’s fixtures and option descriptions, verbatim where they fit.
- Tests that catch real problems. Fixture parity proves the HTML. Unit tests cover only what parity can’t see.
Parts and composites
- A version of a part that renders several elements is named
Composite,Field,XCompositeorXField(Feedback.Composite,ErrorMessageComposite). An SVG counts as one element. - Every element a composite renders is also a part. Re-exported parts keep the composite’s defaults (
Feedback.GridColumnis two-thirds). - Form controls have a
Field. WhereRootis a single element around a list, the item’s composite covers basic usage (TaskList.ItemComposite). - A composite may offer its items as an array prop, as a convenience. It always takes them as children too, never both at once, and its JSDoc recommends children.
- Spaces between inline parts are yours to write, as in HTML.
- Link parts take
asChildto render your router’s link instead of ana, with their classes merged on (<Link asChild><RouterLink to="/">Home</RouterLink></Link>). - Tabs is parts only: its tab list and panels repeat the same ids, so children can’t build both.
API styles by component
- Root: the outermost part, with other parts inside it.
- Single: one part, named after the component.
- Composite:
Composite, orFieldfor form controls, renders basic usage from the parts. - Other composites: parts that render several elements (
XComposite). - Array prop: the composite also takes its items as an array, instead of children.
- Builds on: parts that re-export or wrap another component’s part.
| Component | Root | Single | Composite | Other composites | Array prop | Builds on |
|---|---|---|---|---|---|---|
| Accordion | ✓ | Composite |
SectionComposite |
sections |
||
| Back link | ✓ | |||||
| Breadcrumbs | ✓ | Composite |
ItemComposite |
items |
||
| Button | ✓ | StartButton |
||||
| Character count | ✓ | Field |
Textarea, Hint |
|||
| Checkboxes | ✓ | Field |
ItemComposite |
items |
Label, Hint |
|
| Cookie banner | ✓ | Composite |
MessageComposite |
GridRow, GridColumn, ButtonGroup |
||
| Date input | ✓ | Field |
Label, Input |
|||
| Details | ✓ | Composite |
||||
| Error message | ✓ | ErrorMessageComposite |
||||
| Error summary | ✓ | Composite |
ListItemComposite |
errors |
||
| Exit this page | ✓ | Composite |
Button |
|||
| Feedback | ✓ | Composite |
GridRow, GridColumn |
|||
| Fieldset | ✓ | Composite |
LegendComposite |
|||
| File upload | ✓ | FileUploadField |
||||
| Footer | ✓ | Composite |
LicenceDescriptionComposite |
WidthContainer, Crown |
||
| Generic header | ✓ | Composite |
||||
| Header | ✓ | Composite |
Logotype |
|||
| Hint | ✓ | |||||
| Input | ✓ | InputField |
||||
| Inset text | ✓ | |||||
| Label | LabelComposite |
|||||
| Language navigation | ✓ | Composite |
ItemComposite |
items |
||
| Main wrapper | ✓ | |||||
| Notification banner | ✓ | Composite |
||||
| Pagination | ✓ | Composite |
ItemComposite, PreviousLinkTitleComposite, NextLinkTitleComposite |
items |
||
| Panel | ✓ | Composite |
||||
| Password input | ✓ | Field |
Input, Button |
|||
| Phase banner | ✓ | Composite |
Tag |
|||
| Radios | ✓ | Field |
ItemComposite |
items |
Label, Hint |
|
| Select | ✓ | SelectField |
||||
| Service navigation | ✓ | Composite |
ItemComposite |
items |
WidthContainer |
|
| Skip link | ✓ | |||||
| Summary list | ✓ | Composite, Card.Composite |
RowComposite, ActionComposite |
rows |
||
| Table | ✓ | Composite |
||||
| Tabs | ✓ | |||||
| Tag | ✓ | |||||
| Task list | ✓ | Composite |
ItemComposite |
items |
||
| Template | ✓ | Composite |
HeadComposite |
SkipLink, Header, ServiceNavigation, Footer, WidthContainer, MainWrapper |
||
| Textarea | ✓ | TextareaField |
||||
| Warning text | ✓ |