govuk-frontend compatible React components
This package is no longer maintained and will not receive updates bringing it beyond govuk-frontend 4.0.1. If you are using this in your project the simplest way forward is to copy and paste the components from here into your project allowing you to keep them up to date with govuk-frontend yourselves.
Please note - the version number of govuk-react-jsx is independent of the govuk-frontend version number.
View demo at https://govuk-react-jsx.netlify.app/
View example app at https://surevine.github.io/govuk-react-jsx-examples/ (for which the source code is at https://github.com/surevine/govuk-react-jsx-examples)
If you do not need the characteristics of a Single Page App framework like React, please consider using something else. Government services should be progressively enhanced, and should function without JavaScript enabled.
If you have an explicit requirement that cannot be delivered effectively in a progressively enhanced manner then you might have a case for using React. If you have plans to build your React app in a progressively enhanced way, you might be fine. Whatever you do, be prepared to defend it at a service assessment.
$ npm install govuk-react-jsx
(See installation and usage for more details)
This repository contains govuk-frontend compatible React components. The aim of this package is to steer closely to govuk-frontend by consuming the CSS directly from the govuk-frontend npm package. And to strike a balance between mirroring the GOV.UK Nunjucks params vs ideomatic React props.
This has the following benefits
govuk-react is the other main option in this space. Naturally the first thing people ask is why one might use this repository instead of govuk-react. Here's my take on the matter:
govuk-react | govuk-react-jsx (This repository) |
---|---|
An implementation of the govuk design system. CSS, JS and Markup patterns have all been rewritten from scratch. Aria attributes missing. |
Directly consumes the govuk-frontend CSS/JS and accurately mirrors their markup patterns, including Aria attributes |
Upstream CSS/JS changes in govuk-frontend need to be manually transferred across and/or rebuilt | Upstream CSS/JS changes are pulled in automatically. Only markup changes need to manually transferred (But are validated as correct by the test suite) |
Relatively complex code | Simpler code - just plain JSX ports of the Nunjucks |
Uses StyledComponents Great if you like them and use them. But if you prefer a different library then you would end up needing both in your toolchain. Increased maintenance burden on govuk-react team |
Uses plain Sass compilation of the govuk-frontend code. You are free to use a CSSinJS library of your choice for your own styles if you wish |
Cleaner component props since it has been designed from the ground up for React | Props mostly mirror the govuk-frontend Nunjucks params with some exceptions as below. This has been done in order to steer as closely to govuk-frontend as possible, and to facilitate the test suite checking the output against the original. This is possibly the main argument against this repository and for govuk-react. It's a tradeoff. One that is worth making in my opinion but make your own call on that. |
More comprehensive set of components. Includes components for headings, paragraphs, spacing etc |
Only includes components that are direct equivalents of the Nunjucks templates in govuk-frontend. (Although a future release is planned that will include grid, headings and paragraphs etc.) Spacing classes will likely never be a component in this repository - some things like that I feel are already sufficiently well served by just using the CSS classes directly. This repository does not attempt to abstract you away from the fact that you are using govuk-frontend CSS. |
Allows code splitting of the styles, since they are defined in each component | No code splitting - all GOV.UK CSS is loaded. Although - it is relatively easy to omit the Scss files that you don't need so this is only a small downside |
No complications from integrating with other libraries | As per the React docs on Integrating with other libraries there is a very small chance that the integration of the GOV.UK JS might result in bugs if React tries to update a component that the GOV.UK JS has also updated. This is fairly unlikely but is something to be mindful of. |
These components assume you:
Exceptions to the conformance with govuk-frontend nunjucks params are as follows:
href
/ text
combo of params to create a hyperlink, will also accept a to
prop instead of href
, which will be used in a react-router <Link>
element.homepageUrl
and serviceUrl
become homepageUrlHref
/ homepageUrlTo
and serviceUrlHref
/ serviceUrlTo
, with the To
variants being passed to a react-router <Link>
the Href
variants being a plain html <a>
taghtml
or text
param in Nunjucks will instead accept a children
prop which should be passed either a string, or JSX. Params such as summaryText
or summaryHtml
become summaryChildren
classes
becomes className
spellcheck
becomes spellCheck
inputmode
becomes inputMode
describedBy
becomes aria-describedby
colspan
and rowspan
become colSpan
and rowSpan
autocomplete
becomes autoComplete
ariaLabel
becomes aria-label
reactListKey
for each item. This will be used instead of the index when doing .map
over the items. React uses these keys internally to work out whether to re-render items. This is crucial for dynamic components where you might re-sort the list items for example. For static data it is less important and the key can be omitted. (See https://reactjs.org/docs/lists-and-keys.html#keys for more)
(The only exception to this rule is the tab component, where the tabs are already sufficiently keyed by id)<Select>
component and <Radios>
components take a top level value
prop, instead of setting checked
or selected
on the individual items. This is more in line with React and React-based form libraries<ErrorSummary>
component does not automatically focus itself when errors occur - it is up to the calling app to focus it when appropriate, such as when a submit button is pressed.<Table>
component data structure is changed slightly to accomodate react list keys on table rows. Note the addition of a cells
key inside each row, rather than a simple nested array of rows / cells.See utils/processExampleData.js for the complete list of transformations.
npm install govuk-react-jsx
NB: govuk-react-jsx
has a number of peer dependencies that you will need to install yourself:
A full list can be found in the dependencies
section of /scripts/package.json
An example of setting up create-react-app to use govuk-react-jsx can be viewed in this commit over on govuk-react-jsx-examples.
govuk-react-jsx
uses the same styles as govuk-frontend
, the only difference being styles need to be applied using className
rather than class
as it's React.
e.g. to use govuk-frontend
typography styles:
<p className="govuk-body">
Use this design system to make your service consistent with GOV.UK.
</p>
An example of using govuk-frontend styles with govuk-react-jsx
can be viewed at https://surevine.github.io/govuk-react-jsx-examples/.
All components are documented in Storybook with example usage code.
e.g. to render a panel component
import { Panel } from 'govuk-react-jsx';
<Panel titleChildren="Application complete">
Your reference number: HDJ2123F
</Panel>
An example of using govuk-react-jsx
to create forms using Formik and react-hook-form, complete with error validation can be viewed at https://surevine.github.io/govuk-react-jsx-examples/.
In the case of form components React.forwardRef
is used to forward any ref passed to a component onto the underlying DOM element. For example:
const ref = useRef();
<Input
ref={ref}
id="input-example"
label={{
children: [
'National Insurance number'
]
}}
name="test-name"
type="text"
/>
In this code, ref
will contain a reference to the actual DOM input element. You could use this to then call .focus()
on the element.
For components such as DateInput, Radios, Checkboxes and anywhere that uses an items
prop to represent many form elements to be returned by the component, each object in the items array can accept a ref
key which will then return a reference to the rendered form element for that item.
Rather than adding them everywhere I have currently restricted it to form components where I can imagine a use case. Please open an issue if you need refs forwarded onto other types of elements - I may have missed a use case.
This repository is versioned separately and follows standard semver procedures.
The test suite passes the example data from the govuk-frontend repository through the JSX components and compares the output with the reference output provided in govuk-frontend. Any differences here constitute a failure.
Tests run in Github actions.
Andy Mantell (Primary maintainer)
Mick Jones (Helped to build the original JSX ports found at https://github.com/LandRegistry/govuk-react-components)