Server rendering
Every component renders HTML that works without JavaScript, so you can render your pages on the server. Pages then work while JavaScript is still loading, or if it fails to load, and JavaScript enhances them once it arrives, as govuk-frontend’s does.
We recommend Astro
We recommend Astro, because it lets you use React as a progressive enhancement. Astro renders React components to HTML on the server and sends no JavaScript for them by default. You choose which components hydrate in the browser, as islands, so React only runs where it’s needed. This site is built with Astro.
See our Astro example (source). It has forms that submit and show their errors without JavaScript, islands that hydrate selectively, components enhanced by inline scripts with no React in the browser, and a component that React takes over from its inline script.
Create an Astro project, add React, and install govuk-react:
npm create astro@latest
npx astro add react
npm install govuk-react@alpha govuk-frontend
Render components as HTML
In an Astro page, govuk-react components render to HTML, with no React in the browser:
---
import 'govuk-frontend/dist/govuk/govuk-frontend.min.css';
import 'govuk-react/styles.css';
import { Heading } from 'govuk-react';
import * as Details from 'govuk-react/details';
---
<Heading size="l">Apply for a licence</Heading>
<Details.Composite summary="Help with nationality">
We need to know your nationality so we can work out which elections you're entitled to vote in.
</Details.Composite>
How components are enhanced
Where govuk-frontend adds behaviour in JavaScript, govuk-react uses a primitive from @govuk-react/primitives. Each primitive has two halves:
- a custom element, which enhances the markup as soon as it’s defined, with or without React
- React parts over it, which add state, such as
valueandonValueChange, once React hydrates
Until the element is defined, the component shows its no-JavaScript version. For example, the accordion shows every section, and tabs show every panel. Each example on this site has a “Without JavaScript” option that shows the component as it renders before JavaScript.
Before React hydrates
React’s bundle defines the elements, so by default the enhancement waits for it to download. To enhance the page sooner, inline the elements’ scripts in the head. Each is small, with no imports and no React, and is defined only once, whichever runs first. React’s parts then pick up from the elements, including anything the user did before hydration.
Install the primitives, at the version govuk-react uses, and render the scripts your page needs:
import { InlineScript, accordion, tabs } from '@govuk-react/primitives/inline-script';
<head>
<InlineScript script={accordion} nonce={nonce} />
<InlineScript script={tabs} nonce={nonce} />
</head>;
Pass nonce if your Content Security Policy needs one. InlineScript renders only on the server, so the scripts stay out of your client bundle: it has no 'use client' directive, and in Astro it needs no client:* directive. See inline scripts.
Our Astro example has a page without React, and one where React takes over from the inline script.
Hydrate only what needs React
Where part of a page needs React, such as a form with state, put it in a React component and give it a client directive:
---
import ContactForm from '../components/ContactForm.tsx';
---
<ContactForm client:load />
Only that component, and what it imports, is sent to the browser. Use client:visible or client:idle to hydrate it later. client:visible watches the island’s child elements, and the primitives’ elements have display: contents, so they have no box of their own: wrap a component such as an accordion in a div.
For examples, see islands and forms in our Astro example, and the Forms guide.
Islands
Components work in separate React roots, such as Astro islands, because nothing depends on React context. Where a component’s parts can render in different islands, such as tabs, pass the ids or names that a root would otherwise generate.
Other frameworks
govuk-react also works with other frameworks that render React on the server, such as React Router and Next.js.
Further reading
- Building a robust frontend using progressive enhancement, in the GOV.UK Service Manual
- Resilient Web Design, by Jeremy Keith
- Progressive enhancement is still important, by Jake Archibald