10.4.2 - 25 March 2026

Note: This release was created from the support/10.x branch.

🔧 Fixes

• #1867: Update macro options JSON to include release metadata
• #1868: Update package exports field for shorter Sass pkg: URLs

10.4.1 - 19 March 2026

Note: This release was created from the support/10.x branch.

🔧 Fixes

• #1860: Restore source maps for CSS to CSS output

10.4.0 - 18 March 2026

Note: This release was created from the support/10.x branch.

🆕 New features

Add a modifier class for header inline search or account links

We've added a new .nhsuk-header--inline class and inline Nunjucks option for the header component. This positions the search bar (or account links) inline with the NHS logo on small screens, depending on the length of your service name. For example:

  {{ header({
+   inline: true,
    account: {
      items: [
        {
          text: "Log in",
          href: "/log-in"
        }
      ]
    }
  }) }}

This was added in pull requests #1783: Add support for inline header search or account and #1801: Add Nunjucks options for components with modifier classes.

Add Nunjucks options for components with modifier classes

We've added a new variant Nunjucks option to action links, back links, buttons, breadcrumbs, panels and tables as a simpler alternative to the variant modifier classes. For example:

  {{ button({
    text: "Yes, delete this vaccine",
-   classes: "nhsuk-button--warning"
+   variant: "warning"
  }) }}

For modifiers that can exist together, these are now supported using boolean options, for example:

  {{ radios({
    fieldset: {
      legend: {
        text: "Sort by"
      }
    },
-   classes: "nhsuk-radios--small nhsuk-radios--inline",
+   small: true,
+   inline: true,

With the following boolean options now available:

• Button, checkboxes and radios with small: true
• Date input items with error: true
• Radios with inline: true
• Header navigation with justified: true
• Summary lists with lastRowBorder: false
• Summary lists (and rows) with border: false
• Tags with border: false
• Text input with code: true

We've also added the width option to text and date input items as a simpler alternative to the fixed width classes, for example:

  items: [
    {
      name: "day",
-     classes: "nhsuk-input--width-2"
+     width: 2
    },
    {
      name: "month",
-     classes: "nhsuk-input--width-2"
+     width: 2
    },
    {
      name: "year",
-     classes: "nhsuk-input--width-4"
+     width: 4
    }
  ]

Or with both boolean and width modifiers set together:

  {{ input({
    label: {
      text: "NHS number"
    },
-   classes: "nhsuk-input--width-10 nhsuk-input--code",
+   width: 10,
+   code: true,
    inputmode: "numeric",
    spellcheck: false
  }) }}

We've also added the colour option to the tag component as a simpler way to set a colour:

  {{ tag({
    text: "Delayed",
-   classes: "nhsuk-tag--yellow"
+   colour: "yellow"
  }) }}

This was added in pull request #1801: Add Nunjucks options for components with modifier classes.

🗑️ Deprecated features

Rename Sass variables for secondary and hover border colours

If you use Sass and you've extended or created components that use the following border variables:

• replace $nhsuk-secondary-border-colour with $nhsuk-reverse-border-colour for blue backgrounds
• replace $nhsuk-secondary-border-colour with rgba(nhsuk-colour("white"), 0.2) to preserve transparency
• replace $nhsuk-border-hover-colour with nhsuk-colour("grey-3")

The previous names are deprecated and will be repurposed or removed in a future release.

This change was introduced in pull request #1851: Deprecate secondary and hover border colours.

Rename Nunjucks macro options for component variants

All component variants now use the new variant Nunjucks option so we've deprecated the type and boolean options for cards, notification banners and do and don't lists.

If you're using the card Nunjucks macro:

• replace the feature: true option with variant: "feature"
• replace the primary: true option with variant: "primary"
• replace the secondary: true option with variant: "secondary"
• replace the warning: true option with variant: "warning"
• replace the type: "non-urgent" option with variant: "non-urgent"
• replace the type: "urgent" option with variant: "urgent"
• replace the type: "emergency" option with variant: "emergency"

If you're using the notificationBanner Nunjucks macro:

• replace the type: "success" option with variant: "success"

If you're using the list Nunjucks macro:

• replace the type: "tick" option with icon: "tick"
• replace the type: "cross" option with icon: "cross"

The previous names are deprecated and will be removed in a future release.

♻️ Changes

Hide the character count messages when unnecessary

We've updated the HTML for the character count to hide the count message and textarea description when unnecessary, rather than always reserve vertical space.

If you are not using Nunjucks macros, update your HTML markup using the character count examples in the NHS digital service manual to add the hidden boolean attribute to an:

• empty visible count message with a threshold set but not yet reached
• empty textarea description with neither maxlength nor maxwords set

The previous class names nhsuk-character-count__status--disabled and nhsuk-character-count__message--disabled are deprecated and will be removed in a future release.

This change was introduced in pull request #1796: Hide character count message until threshold is reached.

Update the HTML for do and don't lists

For consistency with the card component, the HTML for do and don't lists has changed.

If you are not using Nunjucks macros, update your HTML markup using the do and don't lists in the NHS digital service manual as follows:

• Add the wrapper <div class="nhsuk-card nhsuk-card--feature"> </div>
• Rename the list <div class="nhsuk-do-dont-list" class attribute to match <div class="nhsuk-card__content"
• Rename the heading <h3 class="nhsuk-do-dont-list__label" class attribute to match <h3 class="nhsuk-card__heading"

+ <div class="nhsuk-card nhsuk-card--feature">
-   <div class="nhsuk-do-dont-list">
+   <div class="nhsuk-card__content">
-     <h3 class="nhsuk-do-dont-list__label">
+     <h3 class="nhsuk-card__heading">
        Do
      </h3>
      <!-- // ... -->
    </div>
+ </div>

This change was introduced in pull request #1801: Add Nunjucks options for components with modifier classes.

Align clickable card styles with expander

Clickable cards now follow the hover and active state styling of expanders. On hover their borders darken, on click they depress like a button. On clickable cards with chevrons, the icon changes colour to match link styles.

This change was introduced in pull request #1804: Update card states for consistency.

Remove table row hover styles

We've removed table row hover styles as they only worked on white backgrounds and were not visible on our default page background colour.

This change was introduced in pull request #1801: Add Nunjucks options for components with modifier classes.

🔧 Fixes

• #1779: Fix header menu width when text size changes
• #1780: Close header menu when clicking or navigating elsewhere
• #1795: Add all page template variables from GOV.UK Frontend
• #1797: Ensure components pass label.id down to the label
• #1807: Fix summary list cells becoming vertically misaligned when a multi-line inline-block element is present
• #1829: Always validate component config schema
• #1854: Fix for nested lists in the contents list

10.3.1 - 19 January 2026

Note: This release was created from the support/10.x branch.

🔧 Fixes

• #1777: Remove extra space when bodyClasses is set
• #1778: Fix link to file upload pluralisation rules documentation

10.3.0 - 13 January 2026

Note: This release was created from the support/10.x branch.

🆕 New features

New file upload component

We've added a new file upload component which:

• makes the file inputs easier to use for drag and drop
• allows the text of the component to be translated
• fixes accessibility issues for users of Dragon, a speech recognition software

To use the fileUpload Nunjucks macro in your service:

{{ fileUpload({
  label: {
    text: "Upload your photo"
  },
  id: "file-upload",
  name: "photo"
}) }}

If you are not using Nunjucks macros, use the following HTML:

<div class="nhsuk-form-group nhsuk-file-upload" data-module="nhsuk-file-upload">
  <label class="nhsuk-label" for="file-upload">
    Upload your photo
  </label>
  <input class="nhsuk-file-upload__input" id="file-upload" name="photo" type="file">
</div>

If you're importing components individually in your JavaScript, which we recommend for better performance, you'll then need to import and initialise the new FileUpload component.

import { createAll, FileUpload } from 'nhsuk-frontend'

createAll(FileUpload)

This change was introduced in pull request #1556: Uplift GOV.UK Frontend file upload component

Interruption panel

We've added a new variant of the panel component with a solid blue background and white text. This can be used as an interruption card.

This was added in pull request #1196: Add interruption panel variant.

Use cards to visually separate multiple summary lists on a single page

You can now wrap a card around summary lists to help you:

• design and build pages with multiple summary lists
• show visual dividers between summary lists
• allow users to apply actions to entire lists

This was added in pull request #1685: Add card enhancement to summary list.

🗑️ Deprecated features

Rename Nunjucks macro options for images

For consistency with other components, Nunjucks macro options for images have changed. The previous names are deprecated and will be removed in a future release.

If you're using the card Nunjucks macro with the imgURL or imgALT options in your service, you should:

• replace the imgURL option with the nested image.src option
• replace the imgALT option with the nested image.alt option

  {{ card({
-   imgURL: "https://service-manual.nhs.uk/assets/blog-prototype-kit.png",
-   imgALT: "Illustration showing icons, design system components and a terminal app. Each one follows a dotted line into a laptop to become a prototype.",
+   image: {
+     src: "https://service-manual.nhs.uk/assets/blog-prototype-kit.png",
+     alt: "Illustration showing icons, design system components and a terminal app. Each one follows a dotted line into a laptop to become a prototype."
+   },
    heading: "Why we are reinvesting in the NHS prototype kit"
  }) }}

If you're using the hero Nunjucks macro with the imageURL option in your service, you should:

• replace the imageURL option with the nested image.src option

  {{ hero({
-   imageURL: "https://service-manual.nhs.uk/assets/blog-prototype-kit.png"
+   image: {
+     src: "https://service-manual.nhs.uk/assets/blog-prototype-kit.png"
+   }
  }) }}

If you're using the image Nunjucks macro with the caption option in your service, you should:

• replace the caption option with the nested caption.text option

  {{ image({
    src: "https://service-manual.nhs.uk/assets/image-example-stretch-marks-600w.jpg",
    alt: "Close-up of a person's tummy showing a number of creases in the skin under their belly button. Shown on light brown skin.",
-   caption: "Stretch marks can be pink, red, brown, black, silver or purple. They usually start off darker and fade over time."
+   caption: {
+     text: "Stretch marks can be pink, red, brown, black, silver or purple. They usually start off darker and fade over time."
+   }
  }) }}

This change was introduced in pull request #1763: Review Nunjucks params for header search and images.

Rename input prefix and suffix HTML class

HTML markup for the input component has been updated to align nhsuk-input-wrapper with other wrapping classes such as nhsuk-main-wrapper and nhsuk-label-wrapper.

If you are not using Nunjucks macros, change the input classes as follows:

• Rename the <div class="nhsuk-input__prefix" class attribute to match <div class="nhsuk-input-wrapper__prefix".
• Rename the <div class="nhsuk-input__suffix" class attribute to match <div class="nhsuk-input-wrapper__suffix".

The previous class names are deprecated and will be removed in a future release.

This change was introduced in pull request #1745: Update input prefix and suffix classes to follow BEM.

Rename Sass variables for customising fonts

We've renamed Sass variables for customising fonts to better align with GOV.UK frontend. You can still use the previous names but we'll remove them in a future breaking release.

If you use Sass and you've customised the fonts that NHS.UK frontend uses:

• replace $nhsuk-font and $nhsuk-font-fallback with $nhsuk-font-family
• rename $nhsuk-font-normal to $nhsuk-font-weight-normal
• rename $nhsuk-font-bold to $nhsuk-font-weight-bold
• rename $nhsuk-include-font-face to $nhsuk-include-default-font-face

- $app-font: "Customised name";
- $app-font-fallback: arial, sans-serif;
+ $app-font-family: "Customised name", arial, sans-serif;

  @forward "nhsuk-frontend/dist/nhsuk" with (
-   $nhsuk-font: $app-font
-   $nhsuk-font-fallback: $app-font-fallback,
+   $nhsuk-font-family: $app-font-family,
-   $nhsuk-include-font-face: false
+   $nhsuk-include-default-font-face: false
  );

  .app-component {
    display: block;
-   font-weight: $nhsuk-font-bold;
+   font-weight: $nhsuk-font-weight-bold;
    @include nhsuk-responsive-margin(4, "bottom");
  }

This change was introduced in pull request #1749: Remove font files for unsupported browsers and align Sass variables with GOV.UK Frontend.

♻️ Changes

Update the HTML for header search

For consistency with header navigation and account, we’ve added new Nunjucks macro options:

• Header search.attributes option
• Header search.classes option
• Header search.method option

We've also updated the HTML for the header search to use an inline smaller button from NHS.UK frontend v10.2.0.

If you are not using Nunjucks macros, update your HTML markup using the header examples in the NHS digital service manual as follows:

• add the novalidate boolean attribute to search form element
• add the novalidate boolean attribute to account item forms

  <search class="nhsuk-header__search">
-   <form class="nhsuk-header__search-form" id="search" action="https://www.nhs.uk/search/" method="get">
+   <form class="nhsuk-header__search-form" id="search" action="https://www.nhs.uk/search/" method="get" novalidate>

- <form class="nhsuk-header__account-form" action="/log-out" method="post">
+ <form class="nhsuk-header__account-form" action="/log-out" method="post" novalidate>
    <button class="nhsuk-header__account-button">

• add the <div class="form-group"> </div> wrapper around the search label, input and button
• add the <div class="nhsuk-input-wrapper"> </div> wrapper around the search input and button
• add the nhsuk-button and nhsuk-button--small classes to the search button
• remove the nhsuk-header__search-submit class from the search button

  <form class="nhsuk-header__search-form" id="search" action="https://www.nhs.uk/search/" method="get" novalidate>
+   <div class="nhsuk-form-group">
      <label class="nhsuk-label nhsuk-u-visually-hidden" for="search-field">
        Search the NHS website
      </label>
+     <div class="nhsuk-input-wrapper">
-       <input class="nhsuk-input nhsuk-header__search-input" id="search-field" name="q" type="search" autocomplete="off" placeholder="Search">
-       <button class="nhsuk-header__search-submit" data-module="nhsuk-button" type="submit">
+       <input class="nhsuk-input" id="search-field" name="q" type="search" autocomplete="off" placeholder="Search">
+       <button class="nhsuk-button nhsuk-button--small" data-module="nhsuk-button" type="submit">
          <svg class="nhsuk-icon nhsuk-icon--search" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="16" height="16" focusable="false" role="img" aria-label="Search">
            <title>Search</title>
            <path d="m20.7 19.3-4.1-4.1a7 7 0 1 0-1.4 1.4l4 4.1a1 1 0 0 0 1.5 0c.4-.4.4-1 0-1.4ZM6 11a5 5 0 1 1 10 0 5 5 0 0 1-10 0Z"/>
          </svg>
        </button>
+     </div>
+   </div>
  </form>

Support for header search HTML without nhsuk-form-group and nhsuk-input-wrapper wrappers is deprecated and will be removed in a future release.

This change was introduced in [pull request #1763: Review Nunjucks params for header search and ima...

10.2.2 - 4 December 2025

Note: This release was created from the support/10.x branch.

🔧 Fixes

• #1731: Fix Nunjucks describedBy empty string handling

10.2.1 - 2 December 2025

Note: This release was created from the support/10.x branch.

🔧 Fixes

• #1726: Fix card modifier scope to allow nested cards

10.2.0 - 1 December 2025

🆕 New features

Use the password input component to help users accessibly enter passwords

The password input component allows users to choose:

• whether their passwords are visible or not
• to enter their passwords in plain text

This helps users use longer and more complex passwords without needing to remember what they've already typed.

This was added in pull request #1574: Uplift GOV.UK Frontend password input component.

Smaller versions of buttons

You can now use smaller versions of buttons by adding the nhsuk-button--small class.

This was added in pull request #1643: Add small buttons and inline form groups.

Add inline buttons to text inputs and select menus

You can now add inline buttons to text inputs and select menus using the formGroup.afterInput Nunjucks options.

{{ input({
  formGroup: {
    afterInput: {
      html: button({
        text: "Search",
        classes: "nhsuk-button--small"
      })
    }
  }
}) }}

This was added in pull request #1643: Add small buttons and inline form groups.

Updated Nunjucks macro options for nested items

For consistency with other components with nested items, we’ve added new Nunjucks macro options:

• Action link and skip link html option
• Checkboxes and radios item classes option
• Contents list item html, classes and attributes options
• Summary list action item classes and attributes options

This was added in pull request #1683: Update Nunjucks macro options for nested items.

Add a modifier class for text input styles that accept codes and sequences

We've added a new .nhsuk-input--code class for the text input component. This improves readability of text inputs that receive codes and sequences (like NHS numbers, security codes or booking references).

You can add it through the classes option when using Nunjucks, or directly in the class attribute of the <input> when using HTML.

This was added in pull request #1617: Add input styling for codes and sequences.

Add a 'divider' Nunjucks option to selects

Newer browsers support using <hr> (horizontal rule) elements inside a <select> element to help visually break up options for better readability.

We've added a new divider Nunjucks option on select items to support this feature. For example:

{{ select({
  label: {
    text: 'Sort by'
  },
  name: 'sort',
  items: [
    {
      value: 'first-name-ascending',
      text: 'First name (A to Z)'
    },
    {
      value: 'first-name-descending',
      text: 'First name (Z to A)'
    },
    {
      divider: true
    },
    {
      value: 'last-name-ascending',
      text: 'Last name (A to Z)'
    },
    {
      value: 'last-name-descending',
      text: 'Last name (Z to A)'
    }
  ]
}
}) }}

This was added in pull request #1701: Support showing dividers between select options.

Add a 'size' Nunjucks option to labels and legends

We've added a new size Nunjucks option to labels and legends as a simpler alternative to the size modifier classes. For example:

  {{ input({
    label: {
      text: 'What is your full name?',
-     classes: "nhsuk-label--l"
+     size: "l"
    }
  }) }}

  {{ radios({
    fieldset: {
      legend: {
        text: "How do you want to be contacted about this?",
-       classes: "nhsuk-fieldset__legend--l"
+       size: "l"
      }
    },
    items: []
  }}

This was added in pull request #1708: Add label, legend and table caption size option.

Add a 'captionSize' Nunjucks option to tables

We've added a new captionSize Nunjucks option to tables as a simpler alternative to the caption modifier classes. For example:

  {{ table({
    caption: "Skin symptoms and possible causes",
-   captionClasses: "nhsuk-table__caption--l",
+   captionSize: "l",
    rows: []
  }) }}

This was added in pull request #1708: Add label, legend and table caption size option.

🗑️ Deprecated features

Rename input wrapper HTML class

Within the input component, change the nhsuk-input__wrapper class to nhsuk-input-wrapper.

The previous class name is deprecated and will be removed in a future release.

This change was introduced in pull request #1643: Add small buttons and inline form groups.

Add or rename card HTML classes

HTML markup for the card component has been updated to simplify how each card variant is identified.

If you are not using Nunjucks macros, change the card classes as follows:

• Add the missing nhsuk-card--primary modifier class to primary cards.
• Remove the unnecessary nhsuk-card__heading--feature modifier class from feature card headings.
• Remove the unnecessary nhsuk-card__content--feature modifier class from feature card content.
• Remove the unnecessary nhsuk-card__content--primary modifier class from primary card content.
• Remove the unnecessary nhsuk-card__content--secondary modifier class from secondary card content.
• Rename the <div class="nhsuk-card--care__heading-container" class attribute to match <div class="nhsuk-card__heading-container".
• Rename the <div class="nhsuk-card--care__heading" class attribute to match <div class="nhsuk-card__heading".

The previous class names are deprecated and will be removed in a future release.

This change was introduced in pull request #1684: Fix inconsistent card BEM modifiers etc.

Rename Sass variable for base font size

If you use the Sass $nhsuk-base-font-size variable, you should rename it to $nhsuk-root-font-size.

The previous name is deprecated and will be removed in a future release.

This change was introduced in pull request #1669: Remove pixel font sizes where unnecessary.

♻️ Changes

Update the HTML for tab panel text content

We've updated the HTML for the tabs component to wrap plain text content within <p> elements.

If you are not using Nunjucks macros, update your HTML markup using the tabs examples in the NHS digital service manual to add the missing <p> </p> wrapper:

  <div class="nhsuk-tabs__panel" id="example-1">
-   Example text content
+   <p>Example text content</p>
  </div>

This change was introduced in pull request #1686: Remove ↑ up and ↓ down arrow key bindings from tabs.

Remove unused top task card class name

We've updated the HTML for the card component to remove the unused nhsuk-card--top-task class and associated topTask Nunjucks option.

If you are not using Nunjucks macros, update your HTML markup using the top task card example in the NHS digital service manual where the nhsuk-card--clickable class is used instead.

🔧 Fixes

• #1635: Resolve Nunjucks template issues flagged by Jinja port
• #1638: Resolve Nunjucks output indentation issues
• #1653: Only show a task list item if not empty
• #1656: Improve button text vertical alignment
• #1657: Fix inconsistent margin in form and button groups
• #1686: Remove ↑ up and ↓ down arrow key bindings from tabs
• #1689: Only show header navigation items if not empty
• #1698: Fix 2px minimum chevron outline-width syntax
• #1699: Prevent date inputs shifting alignment on iOS 18

10.1.0 - 15 October 2025

🆕 New features

Localise character count component

You can now translate the text used by the character count component to:

• show when the maximum number of characters or words is reached
• show the number of characters or words over or under the allowed maximum
• update the textarea description if JavaScript is not available
• announce to screen readers when the textarea is focused

The Nunjucks macro accepts new options so you can customise each message. You can:

• Use charactersAtLimitText or wordsAtLimitText to provide the text that shows when users have reached the limit.
• Use charactersUnderLimitText or wordsUnderLimitText to provide the text that shows when users are under the limit. The component will pluralise the message according to the configured locale and the number of characters or words remaining.
• Use charactersOverLimitText or wordsOverLimitText to provide the text that shows when users are over the limit. The component will pluralise the message according to the configured locale and the number of characters or words remaining.
• Use textareaDescriptionText to provide the textarea description for assistive technologies. It is visible on the page when JavaScript is unavailable.

The component will replace %{count} with the number of characters over or under the limit.

If you're not using Nunjucks macros, you can use data-* attributes to provide these translations. Within the attribute value, any quotation marks or other characters reserved by HTML needs to be converted into their HTML entity equivalents.

You can:

• use data-i18n.characters-at-limit or data-i18n.words-at-limit for when users are at the limit
• configure the text that informs the end user they are under the character or word limit, by using data-i18n.characters-under-limit.{other,many,few,two,one,zero} or data-i18n.words-under-limit.{other,many,few,two,one,zero}, with one suffix for each plural form required by your locale
• configure the text that informs the end user they are over the character or word limit, by using data-i18n.characters-over-limit.{other,many,few,two,one,zero} or data-i18n.words-over-limit.{other,many,few,two,one,zero}, with one suffix for each plural form required by your locale
• configure the description provided to assistive technologies when users focus the input, by using data-i18n.textarea-description.{other,many,few,two,one,zero} to provide the text to set as the description

You can also provide these messages using a JavaScript configuration object when creating an instance of the component or initialising all components. See our guidance on localising NHS.UK frontend for how to do this.

This was added in pull request #1565: Add character count localisation.

Smaller versions of radio buttons and checkboxes

You can now use smaller versions of the radios and checkboxes components by adding the nhsuk-radios--small or nhsuk-checkboxes--small class.

This was added in pull request #1567: Uplift GOV.UK Frontend form field components.

Updated Nunjucks macro options for components

For consistency with other components, we’ve added new Nunjucks macro options:

• Back link visuallyHiddenText option
• Breadcrumbs nested backLink component option
• Contents list landmarkLabel and visuallyHiddenTitle options
• Do and Don't list prefixText option, with nested item text and html options
• Fieldset html and role options
• Header navigation toggleMenuText and toggleMenuVisuallyHiddenText options
• Inset text visuallyHiddenText option
• Pagination previous, next and landmarkLabel options
• Radios item disabled and attributes options
• Text input autocapitalize and disabled options, with prefix and suffix nested text, html, classes and attributes options
• Textarea disabled and spellcheck options
• Warning callout visuallyHiddenText option

Visit the design system in the NHS digital service manual to see Nunjucks options for each component.

This was added in pull request #1567: Uplift GOV.UK Frontend form field components.

Updated appearance of disabled form controls

We’ve updated the disabled state of radio buttons, checkboxes, text inputs, textareas and select menus so it is consistent across browsers and devices.

Disabled form controls appear at 50% opacity and with an alternative cursor appearance when hovered over.

This was added in pull request #1567: Uplift GOV.UK Frontend form field components.

Insert custom HTML into component form group wrappers

You can now insert custom HTML into form group wrappers for all components with form fields.

{{ input({
  formGroup: {
    beforeInput: {
      html: "example"
    },
    afterInput: {
      html: "example"
    }
  }
}) }}

This was added in pull request #1561: Add beforeInput(s) and beforeInput(s) options to form groups.

Numbered pagination component

The pagination component now supports numbered pagination, for example where you have a long list of of items to navigate.

You can use it like this:

pagination({
  previous: {
    href: "#"
  },
  next: {
    href: "#"
  },
  items: [
    {
      number: 1,
      href: "#"
    },
    {
      number: 2,
      href: "#",
      current: true
    },
    {
      number: 3,
      href: "#"
    }
  ]
})

This was added in pull request #1026: Add numbered pagination.

🗑️ Deprecated features

Rename Sass variables for border width and colour

If you use Sass and you've extended or created components that use the following border variables:

• rename $nhsuk-border-width-mobile to $nhsuk-border-width
• rename $nhsuk-border-width-form-element-error to $nhsuk-border-width-form-element

The previous names are deprecated and will be removed in a future release.

This change was introduced in pull request #1594: Always set input :focus box-shadow colour.

♻️ Changes

Do and Don't list Nunjucks options

For consistency with other components, the do and don't list Nunjucks options have changed. The previous names are deprecated and will be removed in a future release.

If you're using the list Nunjucks macro in your service, you should update the nested items option, using text or html instead of item.

  {{ list({
    title: "Do",
    type: "tick",
    items: [
      {
-       item: "cover blisters with a soft plaster or padded dressing"
+       text: "cover blisters with a soft plaster or padded dressing"
      },
      {
-       item: "wash your hands before touching a burst blister"
+       text: "wash your hands before touching a burst blister"
      },
      {
-       item: "allow the fluid in a burst blister to drain before covering it with a plaster or dressing"
+       text: "allow the fluid in a burst blister to drain before covering it with a plaster or dressing"
      }
    ]
  }) }}

This change was introduced in pull request #1620: Make all Nunjucks components text configurable.

Pagination Nunjucks options

For consistency with other components, the pagination Nunjucks options have changed. The previous names are deprecated and will be removed in a future release.

If you're using the pagination Nunjucks macro in your service, you should:

• replace the previousUrl option with the nested previous.href option
• replace the previousPage option with the nested previous.labelText option
• replace the nextUrl option with the nested next.href option
• replace the nextPage option with the nested next.labelText option

  {{ pagination({
-   previousPage: "Treatments",
-   previousUrl: "/section/treatments",
+   previous: {
+     labelText: "Treatments",
+     href: "/section/treatments"
+   },
-   nextPage: "Symptoms",
-   nextUrl: "/section/symptoms"
+   next: {
+     labelText: "Symptoms",
+     href: "/section/symptoms"
+   }
  }) }}

This change was introduced in pull request #1620: Make all Nunjucks components text configurable.

🔧 Fixes

• #1593: Fix Sass deprecated core/settings/colours partial
• #1594: Always set input :focus box-shadow colour
• #1599: Make border colour on nhsuk-panel mixin optional
• #1601: Fix accessible name for linked logo in header component
• #1612: Fix styling of action link when used in emergency cards
• #1628: Fix Node.js ReferenceError: HTMLElement is not defined when imported server-side

10.0.0 - 26 August 2025

You can follow the updating to NHS.UK frontend version 10 guide in the NHS digital service manual on what's changed and what you need to update.

This release introduces some breaking changes to file paths, full width buttons on mobile, the header component and others. It also stops Internet Explorer 11 and other older browsers from running NHS.UK frontend JavaScript.

Your service will not stop working in Internet Explorer 11, but components will look and behave differently without JavaScript. Read more about how we provide support for different browsers.

Service teams should be using a progressive enhancement approach (GOV.UK service manual) to make sure users can still access any content and complete their tasks.

You must read and apply these updates carefully to make sure your service does not break.

🆕 New features

New header component with account section

We’ve updated the header component to support showing account information and links. As part of this work we’ve also made some other improvements to the header:

• show currently active section or page in the navigation
• remove hardcoded home link from the navigation
• align navigation items to the left by default
• update navigation label from ’Primary navigation’ to ‘Menu’, and remove superfluous role and id attributes
• update NHS logo in the header to have higher contrast when focused
• refactor CSS classes and BEM naming, use hidden attributes instead of modifier classes, use generic search element

This was added in pull request #1058: New header with account section.

New notification banner component

We’ve added a new notification banner component, ported from the GOV.UK design system.

This was added in pull request #1408: Add notification banner component.

Buttons are now full width on mobile

All buttons are now displayed at full width on mobile. This may not require any changes, but you should check that it does not break any of your layouts.

Buttons and links can also be grouped together so that they appear side-by-side on tablet and desktop by using a <div class="nhsuk-button-group"> </div> container.

This was added in pull request #1309: Add button group and full width button styles.

Reversed link style for action link

You can now use the action link component on dark backgrounds by using the .nhsuk-action-link--reverse class. Added in pull request #1542: Add reverse action link modifiers and styles.

Sass colour palette nhsuk-colour function

The Sass colour palette variables (e.g. $color_nhsuk-blue) have been moved into a new single $nhsuk-colours map. The previous names are deprecated and will be removed in a future release.

If you need to reference a colour within your application you should use the new nhsuk-colour function:

  .nhsuk-example {
-   color: $color_nhsuk-blue;
+   color: nhsuk-colour("blue");
  }

This was added in pull request #1526: Add $nhsuk-colour palette, colour helpers and deprecate "color" spelling.

Sass colours as CSS custom properties

The Sass applied colour variables (e.g. $nhsuk-link-colour) are now available as CSS custom properties

For example:

--nhsuk-link-colour: #005eb8;
--nhsuk-link-hover-colour: #7c2855;
--nhsuk-link-active-colour: #002f5c;
--nhsuk-link-visited-colour: #330072;

This change was introduced in pull request #1495: Output CSS custom properties from Sass colours.

New JavaScript API for NHS.UK frontend

The JavaScript API for NHS.UK frontend now includes type declarations for better type safety and code autocomplete.

We've also added a new createAll function that lets you initialise specific components in the same way that initAll does:

• find all elements in the page with the corresponding data-module attribute
• initialise a new component for each element
• catch errors and log them in the console
• return an array of all the successfully initialised components.

import { createAll, Button, Checkboxes } from 'nhsuk-frontend'

createAll(Button)
createAll(Checkboxes)

You can also pass a config object and a scope within which to search for elements:

import { createAll, Button, Checkboxes } from 'nhsuk-frontend'

const $element = document.querySelector('.app-modal')

createAll(Button, { preventDoubleClick: true }, $element)
createAll(Checkboxes, undefined, $element)

Similarly, the existing initAll function can also configure components by including key-value pairs of camel-cased component names with their options:

import { initAll } from 'nhsuk-frontend'

initAll({
  button: {
    preventDoubleClick: true
  }
})

You can find out more about how to use the initAll and createAll functions in our documentation.

This was added in pull requests #1464: Export type declarations *.d.mts for NHS.UK frontend and #1506: Add JavaScript configuration support to components.

Create custom width container classes

You can now create custom page width container classes using the nhsuk-width-container mixin. You do this by passing in the required maximum width of the container.

For example:

.app-width-container--wide {
  @include nhsuk-width-container(1200px);
}

You can use the generated classes to set the width of:

• template container
• header container
• footer container

It was already possible to set the page app width with the $nhsuk-page-width variable. This new feature is useful when creating additional custom page width classes.

This was added in pull request #1412: Allow creating custom width containers.

🗑️ Deprecated features

Rename Sass variables, mixins and CSS classes to use "colour" spelling

We've renamed all Sass variables, mixins and CSS classes to use "colour" (not "color") spelling. You can still use the previous names but we'll remove them in a future breaking release.

For example, the following variables have been renamed to replace -color with -colour:

• $nhsuk-link-color renamed to $nhsuk-link-colour
• $nhsuk-link-hover-color renamed to $nhsuk-link-hover-colour
• $nhsuk-link-active-color renamed to $nhsuk-link-active-colour
• $nhsuk-link-visited-color renamed to $nhsuk-link-visited-colour

With the following variables renamed to align with GOV.UK Frontend:

• $nhsuk-form-border-color renamed to $nhsuk-input-border-colour
• $nhsuk-form-element-background-color renamed to $nhsuk-input-background-colour

See pull request #1526 for the full list.

The following Sass mixins have been renamed:

• nhsuk-print-color renamed to nhsuk-print-colour
• nhsuk-text-color renamed to nhsuk-text-colour

The following CSS classes have been renamed:

• nhsuk-u-secondary-text-color renamed to nhsuk-u-secondary-text-colour

This change was introduced in pull request #1526: Add $nhsuk-colour palette, colour helpers and deprecate "color" spelling.

💥 Breaking changes to stylesheets

The file structure for the stylesheets has changed. You will have to make different updates depending on whether you are compiling the Sass files or using the precompiled CSS.

Precompiled CSS

For precompiled CSS files, note the following path changes:

• copy or serve node_modules/nhsuk-frontend/dist/nhsuk/nhsuk-frontend.min.css
  – not the previous node_modules/nhsuk-frontend/dist/nhsuk.min.css stylesheet
• extract nhsuk-frontend-<VERSION-NUMBER>.min.css from the GitHub release zip file
  – not the previous css/nhsuk-<VERSION-NUMBER>.min.css stylesheet

Sass files

If you are compiling the Sass files, you must add node_modules to Sass load paths, by either:

• calling the Sass compiler from the command line with the --load-path node_modules flag
• using the JavaScript API with loadPaths: ['node_modules'] in the options object

Replace packages with dist/nhsuk for any @forward, @use or @import paths in your Sass files, making sure to remove the unnecessary node_modules/ prefix:

- @import "node_modules/nhsuk-frontend/packages/nhsuk";
+ @import "nhsuk-frontend/dist/nhsuk";

Sass deprecated colours removed

Sass colour tint and shade variables (e.g. $color_tint_nhsuk-black-10) have been removed but are available using the nhsuk-tint and nhsuk-shade functions: