Skip to content

LandRegistry/govuk-react-components-library

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

46 Commits
.github
.github
 
 
.husky
.husky
 
 
.storybook
.storybook
 
 
assets
assets
 
 
scripts
scripts
 
 
src
src
 
 
.dockerignore
.dockerignore
 
 
.gitattributes
.gitattributes
 
 
.gitignore
.gitignore
 
 
.gitlab-ci.yml
.gitlab-ci.yml
 
 
.npmignore
.npmignore
 
 
.npmrc
.npmrc
 
 
.nvmrc
.nvmrc
 
 
.stylelintrc.json
.stylelintrc.json
 
 
Architecture.md
Architecture.md
 
 
CHANGELOG.md
CHANGELOG.md
 
 
CODE_OF_CONDUCT.md
CODE_OF_CONDUCT.md
 
 
CONTRIBUTING.md
CONTRIBUTING.md
 
 
Dockerfile
Dockerfile
 
 
LICENCE
LICENCE
 
 
README.md
README.md
 
 
bundle-analysis-main.html
bundle-analysis-main.html
 
 
bundle-analysis-pdfvc.html
bundle-analysis-pdfvc.html
 
 
chromatic.config.json
chromatic.config.json
 
 
commitlint.config.js
commitlint.config.js
 
 
eslint.config.mjs
eslint.config.mjs
 
 
first.md
first.md
 
 
package-lock.json
package-lock.json
 
 
package.json
package.json
 
 
rollup.config.mjs
rollup.config.mjs
 
 
tsconfig.json
tsconfig.json
 
 

Repository files navigation

GOVUK React Components Library

Latest release NPM version GOV.UK Frontend version Node version Licence

This project is a collection of React components built based on GDS Specifications. The components are designed to be reused by applications, with a focus on providing consistent and accessible user experiences. The components are based on the govuk-frontend library, ensuring compatibility and adherence to the UK Government's digital design standards.

Disclaimer

⚠️ This project is not officially supported by the Government Digital Service (GDS). It is maintained on a best-efforts basis by the HM Land Registry (HMLR) only. While we strive to ensure the accuracy and reliability of the code, we cannot guarantee its full compliance with GDS standards or the availability of ongoing support.

Installation

Then install this component library:

npm install @hmlr/govuk-react-components-library

Components

You can explore the components in chromatic.

Note that any component with a 👈🏽 below means that - This component will need javascript to be enabled because of the transitions present in the components using createAll or initAll recommended by govuk-frontend documentation

The Components includes:

There are Also Several components that can be used for error processing and other functionality like dashboard display: Note that some of the components below with 👈🏽 - Means like the above components, javascript needs to be enabled.

There are also some useful components :

There are some convenience functions that can be used to configure components with 👈🏽 mentioned above.

Here are some examples of the above convenient configurations functions:

Scoped Accordion Configuration Example 
// in scope accordion configuration
import React, { useEffect } from "react";
import {
  ConfigureOverallAccordion,
  ExtractAccordionConfigFromAttributes,
} from "@hmlr/govuk-react-components-library";

function App() {
  useEffect(() => {
    const attributes = {
      hideAllSectionsText: "Collapse all sections",
      showAllSectionsText: "Expand all sections",
      hideSectionText: "Collapse",
      hideSectionAriaLabelText: "Collapse this section",
      showSectionText: "Expand",
      showSectionAriaLabelText: "Expand this section",
    };
    const accordionConfig = ExtractAccordionConfigFromAttributes(attributes);
    const $element = document.querySelector(".govuk-accordion");
    ConfigureOverallAccordion($element, accordionConfig);
  }, []);

  return (
    <Accordion
      id="default-example"
      items={[
        {
          content: {
            children:
              "We need to know your nationality so we can work out which elections you’re entitled to vote in. If you cannot provide your nationality, you’ll have to send copies of identity documents through the post.",
          },
          heading: {
            children: "Section A",
          },
        },
        {
          content: {
            children: [
              <ul key="0" className="govuk-list govuk-list--bullet">
                {""}
                <li>Example item 2</li>
              </ul>,
              "\n",
            ],
          },
          heading: {
            children: "Section B",
          },
        },
      ]}
    />
  );
}

or

// in scope accordion configuration
import React, { useEffect } from "react";
import {
  Accordion,
  ConfigureOverallAccordion,
} from "@hmlr/govuk-react-components-library";

function App() {
  useEffect(() => {
    const accordionConfig = {
      i18n: {
        hideAllSections: "Collapse all sections",
        showAllSections: "Expand all sections",
        hideSection: "Collapse",
        hideSectionAriaLabel: "Collapse this section",
        showSection: "Expand",
        showSectionAriaLabel: "Expand this section",
      },
    };
    const $element = document.querySelector(".govuk-accordion");
    ConfigureOverallAccordion($element, accordionConfig);
  }, []);

  return (
    <Accordion
      id="default-example"
      items={[
        {
          content: {
            children:
              "We need to know your nationality so we can work out which elections you’re entitled to vote in. If you cannot provide your nationality, you’ll have to send copies of identity documents through the post.",
          },
          heading: {
            children: "Section A",
          },
        },
        {
          content: {
            children: [
              <ul key="0" className="govuk-list govuk-list--bullet">
                {""}
                <li>Example item 2</li>
              </ul>,
              "\n",
            ],
          },
          heading: {
            children: "Section B",
          },
        },
      ]}
    />
  );
}
Scoped Accordion Configuration Example in HTML 
<!-- in scope accordion configuration -->
<script type="module" src="./govuk-frontend.min.js"></script>
<script type="module">
  import { Accordion, createAll } from "./govuk-frontend.min.js";
  const $accordion = document.querySelector(".govuk-accordion");
  createAll(
    Accordion,
    {
      i18n: {
        hideAllSections: "Collapse all sections",
        showAllSections: "Expand all sections",
        hideSection: "Collapse",
        hideSectionAriaLabel: "Collapse this section",
        showSection: "Expand",
        showSectionAriaLabel: "Expand this section",
      },
    },
    $accordion,
  );
</script>

or

<!-- in scope accordion configuration -->
<script type="module" src="./govuk-frontend.min.js"></script>
<script type="module">
  import { Accordion } from "./govuk-frontend.min.js";
  const $accordions = document.querySelectorAll(
    '[data-module="govuk-accordion"]',
  );
  $accordions.forEach(($accordion) => {
    new Accordion($accordion, {
      i18n: {
        hideAllSections: "Collapse all sections",
        showAllSections: "Expand all sections",
        hideSection: "Collapse",
        hideSectionAriaLabel: "Collapse this section",
        showSection: "Expand",
        showSectionAriaLabel: "Expand this section",
      },
    });
  });
</script>
Use default Accordion Configurations 
// use default configuration
import React, { useEffect } from "react";
import {
  Accordion,
  ConfigureOverallAccordion,
} from "@hmlr/govuk-react-components-library";

function App() {
  useEffect(() => {
    ConfigureOverallAccordion();
  }, []);

  return (
    <Accordion
      id="default-example"
      items={[
        {
          content: {
            children:
              "We need to know your nationality so we can work out which elections you’re entitled to vote in. If you cannot provide your nationality, you’ll have to send copies of identity documents through the post.",
          },
          heading: {
            children: "Section A",
          },
        },
        {
          content: {
            children: [
              <ul key="0" className="govuk-list govuk-list--bullet">
                {""}
                <li>Example item 2</li>
              </ul>,
              "\n",
            ],
          },
          heading: {
            children: "Section B",
          },
        },
      ]}
    />
  );
}

or in html

<!-- use default configuration -->
<script type="module" src="./govuk-frontend.min.js"></script>
<script type="module">
  import { Accordion, createAll } from "./govuk-frontend.min.js";
  createAll(Accordion);
</script>
Use default All Configurations 
// use default configuration
import React, { useEffect } from "react";
import { initAll } from "govuk-frontend";
import { Accordion } from "@hmlr/govuk-react-components-library";

function App() {
  useEffect(() => {
    initAll();
  }, []);

  return (
    <Accordion
      id="default-example"
      items={[
        {
          content: {
            children:
              "We need to know your nationality so we can work out which elections you’re entitled to vote in. If you cannot provide your nationality, you’ll have to send copies of identity documents through the post.",
          },
          heading: {
            children: "Section A",
          },
        },
        {
          content: {
            children: [
              <ul key="0" className="govuk-list govuk-list--bullet">
                {""}
                <li>Example item 2</li>
              </ul>,
              "\n",
            ],
          },
          heading: {
            children: "Section B",
          },
        },
      ]}
    />
  );
}

or in html

<!-- use default configuration -->
<script type="module" src="./govuk-frontend.min.js"></script>
<script type="module">
  import { initAll } from "./govuk-frontend.min.js";
  initAll();
</script>

Pagination migration

The Pagination component API changed in v1.1.0. The previous API was computation-driven — you supplied raw counts and the component calculated the page range internally. The new API is render-driven: you supply the exact items to display, mirroring the GOV.UK Design System pagination fixture shape. This means the rendered HTML matches the Design System exactly and consumers have full control over what is shown.

Basic numbered pagination

Before (v1.0.3 and earlier)

import { Pagination } from "@hmlr/govuk-react-components-library";

<Pagination
  onPageChange={setPage}
  currentPage={2}
  totalCount={75}
  pageSize={25}
/>;

After (v1.1.0+)

import { Pagination } from "@hmlr/govuk-react-components-library";

<Pagination
  previous={{ href: "/page/1" }}
  next={{ href: "/page/3" }}
  items={[
    { number: 1, href: "/page/1" },
    { number: 2, href: "/page/2", current: true },
    { number: 3, href: "/page/3" },
  ]}
/>;
First page (no previous link)

Before

<Pagination
  onPageChange={setPage}
  currentPage={1}
  totalCount={75}
  pageSize={25}
/>

After — omit previous, the component renders no previous link

<Pagination
  next={{ href: "/page/2" }}
  items={[
    { number: 1, href: "/page/1", current: true },
    { number: 2, href: "/page/2" },
    { number: 3, href: "/page/3" },
  ]}
/>
Many pages with ellipsis

Before

<Pagination
  onPageChange={setPage}
  currentPage={10}
  totalCount={400}
  pageSize={10}
  siblingCount={1}
/>

After — ellipsis positions are explicit via { ellipsis: true } items

<Pagination
  previous={{ href: "/page/9" }}
  next={{ href: "/page/11" }}
  items={[
    { number: 1, href: "/page/1" },
    { ellipsis: true },
    { number: 9, href: "/page/9" },
    { number: 10, href: "/page/10", current: true },
    { number: 11, href: "/page/11" },
    { ellipsis: true },
    { number: 40, href: "/page/40" },
  ]}
/>
Previous / next only with labels (block layout)

Before

<Pagination
  onPageChange={setPage}
  currentPage={2}
  totalCount={50}
  pageSize={25}
  previousName="Previous page"
  nextName="Next page"
  previousChildren={
    <span className="govuk-pagination__link-label">Paying VAT and duty</span>
  }
  nextChildren={
    <span className="govuk-pagination__link-label">
      Registering an imported vehicle
    </span>
  }
/>

After — omitting items automatically applies govuk-pagination--block layout

<Pagination
  previous={{
    href: "/page/1",
    children: "Previous page",
    labelText: "Paying VAT and duty",
  }}
  next={{
    href: "/page/3",
    children: "Next page",
    labelText: "Registering an imported vehicle",
  }}
/>
Computing items dynamically with UsePagination

If your page data is calculated at runtime, UsePagination is still available as a standalone hook. Call it yourself and map the result to the items format:

import {
  Pagination,
  UsePagination,
  DOTS,
} from "@hmlr/govuk-react-components-library";

function SearchResults({ totalCount, pageSize, currentPage, onPageChange }) {
  const totalPages = Math.ceil(totalCount / pageSize);

  const items = UsePagination({
    totalCount,
    pageSize,
    siblingCount: 1,
    currentPage,
  })?.map((entry) =>
    entry === DOTS
      ? { ellipsis: true }
      : {
          number: entry,
          href: `/results?page=${entry}`,
          current: entry === currentPage,
        },
  );

  return (
    <Pagination
      previous={
        currentPage > 1
          ? { href: `/results?page=${currentPage - 1}` }
          : undefined
      }
      next={
        currentPage < totalPages
          ? { href: `/results?page=${currentPage + 1}` }
          : undefined
      }
      items={items}
    />
  );
}

Removed props

Removed prop Replacement
onPageChange Handle navigation via href on previous / next / items
currentPage Set current: true on the relevant item in items
totalCount Not needed — pass items directly
pageSize Not needed — pass items directly
siblingCount Not needed — control ellipsis placement via items
previousName previous.children
nextName next.children
previousChildren previous.labelText
nextChildren next.labelText

Usage

Use the above components like the Panel component:

import { Panel } from "@hmlr/govuk-react-component-library";

export default function SuccessPanel() {
  return (
    <Panel titleChildren="Application complete">
      Your reference number: HDJ2123F
    </Panel>
  );
}

Customizing components

You can customize the appearance and behavior of components by passing props:

import { Button } from "@hmlr/govuk-react-component-library";

export default function CustomButton() {
  return (
    <Button variant="warning" onClick={() => alert("Button clicked!")}>
      Custom Button
    </Button>
  );
}

Note: For the PDFViewer above you must provide a PDFJS Distribution version to be used along with the PDFViewer component. follow the steps to use PDFViewer component:

  • Download any version of the PDFJS Distribution version suitable for your application
  • Unzip the distribution and add it into you project's static directory i.e. public directory. Meaning in the root of your project you will have the distribution in public/pdfjs-4.4.168-dist
  • Use the viewer located in public/pdfjs-4.4.168-dist/web/viewer.html as viewerLocation value in the PDFViewer component. Meaning since public is the static directory the viewer is located in /pdfjs-4.4.168-dist/web/viewer.html.

An example of the PDFViewer component usage based on the 3 steps above will be:

import {
  PDFViewer,
  PDFViewerBackend,
} from "@hmlr/govuk-react-component-library";

export default function ViewDocument() {
  return (
    <PDFViewer
      backend={PDFViewerBackend}
      documentName="LCOP 2020-0035"
      iframeId="document_iframe"
      src="/document.pdf"
      toolbar="fullHidePrint"
      viewerLocation="/pdfjs-4.4.168-dist/web/viewer.html"
    />
  );
}

or base64 encoded pdf data

import {
  PDFViewer,
  PDFViewerBackend,
} from "@hmlr/govuk-react-component-library";
import { base64EncodedPDFDocument } from "./testutilities/SampleBase64";

export default function ViewDocument() {
  return (
    <PDFViewer
      backend={PDFViewerBackend}
      documentName="LCOP 2020-0035"
      iframeId="document_iframe"
      src={base64EncodedPDFDocument}
      toolbar="fullHidePrint"
      viewerLocation="/pdfjs-4.4.168-dist/web/viewer.html"
    />
  );
}

Also one can add custom javascript to viewer to hide or show certain parts of the PDF Viewer or any custom functionality. An example is in the Custom Toolbar in this project. Which then means that in the PDF Viewer. one will add

<script src="../../customToolbar.js"></script>

to the head tag of the ./.storybook/public/pdfjs-4.4.168-dist/web/viewer.html file.

But for the example above we recommend to use the Custom Toolbar in this project. This is tested against /pdfjs-4.4.168-dist only. Copy Custom Toolbar into your project static folder where it is called public and the use it in the public/pdfjs-4.4.168-dist/web/viewer.html thus:

<head>
  .....
  <script src="../../customToolbar.js"></script>
</head>

Using this library

In order to use this library, you will need to install the peer dependencies of this application as show in the package.json.peerDependencies. Which includes the following dependencies:

The source of truth can be found the package.json.peerDependencies.

Using the PDFViewerCanvas Component

The PDFViewerCanvas component is optional and requires the pdfjs-dist package. To use it:

  1. Install the optional dependency:
npm install pdfjs-dist
  • pdfjs-dist - any version >=4.6.82 and only if you are using PDFViewerCanvas component. This is an optional dependency.
  1. Import the PDFViewerCanvas component from the separate entry point:
import { PDFViewerCanvas } from "@hmlr/govuk-react-components-library/pdfViewer";
  1. Use the component in your React application:
<PDFViewerCanvas src="path/to/your/pdf" />

Development

Prerequisites

  • Node.js ( v20.19.0 or higher)
  • npm ( v10.8.2 or higher)
  • govuk-frontend (v5.8.0 or higher)
  • react (v18.2.0 or higher)
  • react-dom (v18.2.0 or higher)
  • react-router-dom (v18.2.0 or higher)

Setup

  1. Clone the repository:
git clone https://github.com/LandRegistry/govuk-react-component-library.git
cd govuk-react-component-library
  1. Install dependencies:
npm install
npm install pdfjs-dist@4.10.38 --save-dev # for PDFCanvas
  1. Start the development server:
npm run dev
  1. Run Storybook:
npm run storybook

Running Builds

To run the build in this project use the following command:

npm run build

Running Linting and formatting

To run the linting and formating in this project use the following command:

npm run lint

or

npm run lint-fix

and for prettifying

npm run format

Testing

To run the test in this project use the following command:

npm run test

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

UML Diagram

The UML diagram for all components in this library can be found here:

HMLR react common library UML

Release New version of this package

Use the floowing command to release a new version of the application

npm run release

or

npm run release -- --release-as minor

or for specific versions

npm run release -- --release-as 1.9.1

Then publish the version with the following command

git push --follow-tags origin main

and publish as an npm package run

npm config set //registry.npmjs.org/:_authToken={$NPM_TOKEN}
npm publish

License

This project is licensed under the MIT License - see the LICENSE file for details.

About

Common component use for React applications based on GDS and govuk-frontend

67da9f53fd479dc895c4293f-dlxeprbnoj.chromatic.com

Topics

react govuk gds govuk-frontend

Resources

Readme

License

MIT license

Code of conduct

Code of conduct

Contributing

Contributing
Activity
Custom properties

Stars

0 stars

Watchers

3 watching

Forks

1 fork
Report repository

Releases 1

First Release Latest
Mar 18, 2025

Packages

 
 
 

Contributors

Languages