@govuk-one-login/frontend-ui

中文文档
5.3.10发布于 2026/11/06ISCTypeScriptESM + CJS构建来源已验证近 30 天下载 6221

Coverage

原始使用文档
文档目录12 节
  1. Frontend UI Component Integration Guide
  2. 1. Installation
  3. 2. Configure View Path
  4. 3. Configure Nunjucks to use exported functions
  5. 4. Load Translations and Configure Middleware
  6. 5. Import Macro
  7. 6. Import all.css
  8. 7. Add Component to Template
  9. Identity Teams Only
  10. 8. Import frontend JS
  11. On Page Load has now been added to basefiles
  12. 1. Render component in the progress button template and pas…

Coverage

@govuk-one-login/frontend-ui

Frontend UI Component Integration Guide

This guide outlines the steps to integrate Frontend UI components into your Node.js application using Nunjucks templating.

1. Installation

Install the NPM package:

npm install @govuk-one-login/frontend-ui

2. Configure View Path

Add the component's path to your Nunjucks view paths in your application's startup file (e.g., app.js or index.js):

const path = require('path');

// ... other configurations ...

app.set(
 'view engine',
 configureNunjucks(app, [
    // ... other view paths ...
    path.resolve('node_modules/@govuk-one-login/frontend-ui')
  ]),
);

Warning: Ensure the path to your node_modules folder is correct.

3. Configure Nunjucks to use exported functions

In your config/nunjucks file import and set the following to use the language toggle, phase banner etc..

Javascript:

const frontendUi = require("@govuk-one-login/frontend-ui");

nunjucksEnv.addGlobal("addLanguageParam", frontendUi.addLanguageParam);
nunjucksEnv.addGlobal("contactUsUrl", frontendUi.contactUsUrl);
nunjucksEnv.addGlobal("MAY_2025_REBRAND_ENABLED", process.env.MAY_2025_REBRAND_ENABLED == "true");

Typescript:

import {contactUsUrl, addLanguageParam } from "@govuk-one-login/frontend-ui";
nunjucksEnv.addGlobal("addLanguageParam", addLanguageParam);
nunjucksEnv.addGlobal("contactUsUrl", contactUsUrl);
nunjucksEnv.addGlobal("MAY_2025_REBRAND_ENABLED", process.env.MAY_2025_REBRAND_ENABLED == "true");

In order to use the MAY_2025_REBRAND_ENABLED variable you will need to create or add to your .env file the following MAY_2025_REBRAND_ENABLED=[true/false]

4. Load Translations and Configure Middleware

In your app.js, import necessary functions and load translations after initializing i18next (Identity teams may need to use the bypass function as their i18n setup is different):

const {
setBaseTranslations
 setFrontendUiTranslations,
 frontendUiMiddleware,
} = require('@govuk-one-login/frontend-ui');

// ... other configurations ...

i18next
  .use(Backend)
  .use(i18nextMiddleware.LanguageDetector)
  .init(
    {
      ...i18nextConfigurationOptions(
        path.join(__dirname, 'locales/{{lng}}/{{ns}}.json'),
      ),
    },
    (err) => {

      if (err) {
        console.error('i18next init failed:', err);
      }
    },
  );

// Apply the middleware
setBaseTranslations(i18next);
setFrontendUiTranslations(i18next); 
app.use(i18nextMiddleware.handle(i18next));
app.use(frontendUiMiddleware);

// For Identity teams a language setting bypass may be required, first import the bypass function and then configure router to use the new function at the top of your router.use functions

const {
 frontendUiMiddlewareIdentityBypass,
} = require('@govuk-one-login/frontend-ui');
....

router.use(frontendUiMiddlewareIdentityBypass);

5. Import Macro

Import the desired component macro into your base Nunjucks template. For example, to use the Cookie Banner component:

{% from "frontend-ui/build/components/cookie-banner/macro.njk" import frontendUiCookieBanner %}

To replace your basefile you need to change the appropriate extension at the top of your view file:

{% extends "frontend-ui/build/components/bases/identity/identity-base-form.njk" %}

or 

{% extends "frontend-ui/build/components/bases/identity/identity-base-page.njk" %}

6. Import all.css

The way is to import the frontend-ui all.css directly into the bottom of your existing css file

@import "../../../node_modules/@govuk-one-login/frontend-ui/build/all";

7. Add Component to Template

Render the component in your template, passing any required data. For the Cookie Banner:

{{ frontendUiCookieBanner({
  translations: translations.translate.cookieBanner 
}) }}

This setup ensures that translations are loaded correctly and the middleware can set necessary local variables for the components to function properly.

Identity Teams Only

Identity teams will also need to install the optional dependency hmpo-components and the basefiles

To replace your basefile you need to change the appropriate extension at the top of your view file:

{% extends "frontend-ui/build/components/bases/identity/identity-base-form.njk" %}

or 

{% extends "frontend-ui/build/components/bases/identity/identity-base-page.njk" %}

8. Import frontend JS

If you need to use a component that incorporates frontend (ie. in-browser) code then you will also need to include the frontend javascript bundle by either importing it in to you existing frontend bundling solution if you use one, or copying and exposing the esm version (@govuk-one-login/frontend-ui/build/esm/frontend/index.js) in your public folder. Then add the script tag on to any page where you use it.

  <script nonce='{{ cspNonce }}' defer type="module" src="/public/javascripts/frontend-ui.js"></script>
  <script nonce='{{ cspNonce }}' defer type="module">
    import { useSpinner } from "/public/javascripts/frontend-ui.js";
    useSpinner();
  </script>

Upgrading to V2

On Page Load has now been added to basefiles

When upgrading to major version 2, GA4 on page load will be within the idenity and core basefiles, this will be a breaking change and implement some duplication on pages if GA4OPL is already being used on them

Implementation Guide - Progress Button

When to use the Progress Button

The progress button has veen designed for implementation in use cases such as when the user has clicked to submit a form and the request is in progress.

The aim is to prevent multiple submissions of forms and provide a visual cue whilst the page is loading.

It should be used when there is more than a 2 second delay and less than a 10 second delay between the user clicking the button and seeing the result.

It is best suited to actions which trigger submission of information to an external API or performing short Back End processes.

When not to use the Progress Button

This should not be used when a user needs to take further action for example when checking their email, opening another app, or retrieving a security code.

The Progress button should not be used when there is less than a 2 second delay between clicking the button and seeing the outcome.

Similarly the button should not be used when there is a delay of more than 10 seconds.

when is it applicable and when is it not?

How to implement the progress button.

1. Render component in the progress button template and pass in the necessary data

Provided the above integration steps have been followed (Frontend UI Component Integration Guide) it should be possible to utilise the progress button by adding to the template as below.

 {{ frontendUiProgressButton({
   translations: translations.translation.progressButton,
   href: "#",
   errorPage: '/404'
 }) }}

版本与发布记录

@govuk-one-login/frontend-ui 共发布 61 个版本,首次发布于 2025/01/16;过去 12 个月发布了 27 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
5.3.10latest2026/11/0610 天前
5.3.92026/11/0313 天前
5.3.82026/11/0214 天前
5.3.72026/11/0214 天前
5.3.62026/10/131 个月前
5.3.52026/09/281 个月前

关于 @govuk-one-login/frontend-ui 的常见问题

如何安装 @govuk-one-login/frontend-ui?

在项目目录运行 npm install @govuk-one-login/frontend-ui,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:express(^5.1.0 || >= 4.21.2)、nunjucks(^3.2.4)、govuk-frontend(^4.10.1 || ^5.0.0)、@govuk-one-login/frontend-logger(^0.0.2)、@govuk-one-login/frontend-analytics( ^3.0.1 || ^4.0.3)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@govuk-one-login/frontend-ui 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@govuk-one-login/frontend-ui 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@govuk-one-login/frontend-ui 可以商用吗?

@govuk-one-login/frontend-ui 使用 ISC 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@govuk-one-login/frontend-ui 的下载量有多少?

根据 npm 官方下载统计,@govuk-one-login/frontend-ui 在 2026/10/17 – 2026/11/15 这 30 天内被下载 6,221 次,日均约 207 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@govuk-one-login/frontend-ui 还在维护吗?

最新版本 5.3.10 发布于 2026/11/06(10 天前);至今共发布 61 个版本,其中过去 12 个月发布了 27 个;首次发布于 2025/01/16。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。