Skip to main content

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 value and onValueChange, 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