govuk-frontend - npm Package Versions

published 4.4.1 • 2 years ago

Changelog

4.4.1 (Fix release)

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

Fixes

We've made fixes to GOV.UK Frontend in the following pull requests:

#3087: Fix focus styles for links split over multiple lines in Chromium 108+ (Chrome 108+, Edge 108+, Opera 94+)

4.4.0

published 4.4.0 • 2 years ago

Changelog

4.4.0 (Feature release)

New features

Change the Button component's background and text colour

For non-GOV.UK branded websites, you can now change the Button component background and text colour.

To change the Button component background colour, set the $govuk-button-background-colour Sass variable.

To change the Button component text colour, set the $govuk-button-text-colour Sass variable.

@import "node_modules/govuk-frontend/govuk/base";

$govuk-button-background-colour: govuk-colour("yellow");
$govuk-button-text-colour: govuk-colour("black");
@import "node_modules/govuk-frontend/govuk/components/button/index";

This was added in pull request #2752: Change the Button component background and text colour. Thanks to Nick Colley for this contribution.

Localise the navigation menu toggle button

When using the header Nunjucks macro, you can now translate the text of the mobile navigation menu toggle button by using the menuButtonText parameter.

You should avoid lengthy values for the menuButtonText parameter. If the text is too long it can overflow and cause visual issues.

This was added in pull request #2720: Add parameter to localise mobile menu toggle button.

Localise the character count's textarea description/fallback text

When using the character count Nunjucks macro, you can now translate the description of textarea by using the textareaDescriptionText option.

This text is announced by screen readers when the character count input is focused. It's also displayed visually as a fallback if JavaScript is not available.

This was added in pull request #2742: Add ability to customise character count fallback text, and the option renamed to textareaDescriptionText in pull request #2915.

Localise the character count's counter message

You can now translate the text shown by the character count component to inform users of:

when they have reached the maximum number of characters or words
the number of characters or words over or under the allowed maximum

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.

You'll find guidance about the plural forms in our documentation about localising GOV.UK Frontend. 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

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 GOV.UK Frontend for how to do this.

This was added in the following pull requests:

Localise the character count's input description for assistive technologies

When configuring the character count's limit in JavaScript, you can customise the description provided to assistive technologies when users focus the input (so it indicates the overall limit of characters or words).

Depending on the plural form required by your locale, you can pass the description in the HTML using the data-i18n.textarea-description.{other,many,few,two,one,zero} attribute on the element to provide the text to set as the description.

This was added in pull request #2915.

Localise the accordion's toggle buttons

You can now translate the text of the accordion component's show and hide toggle buttons.

When using the Nunjucks macro, you can use the new showSectionText and hideSectionText parameters to customise the text of the 'show' and 'hide' toggles in each section.

You can also use showAllSectionsText and hideAllSectionsText parameters to customise the text of the toggle at the top of the accordion.

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

data-i18n.show-section
data-i18n.show-section-aria-label
data-i18n.hide-section
data-i18n.hide-section-aria-label
data-i18n.show-all-sections
data-i18n.hide-all-sections

You can also change this text for all instances of the Accordion using a JavaScript configuration object. See our guidance on localising GOV.UK Frontend for how to do this.

This was added in pull requests:

Suppress deprecation warnings

You can now suppress warnings from deprecations within GOV.UK Frontend by updating the $govuk-suppressed-warnings map in Sass. Every deprecation warning will now include a warning "key" which you can use in the following code, placed at the root of your sass project:

$govuk-suppressed-warnings: (
  deprecated-feature
);

This was added in #2911 Add warning suppression functionality

Configure components in JavaScript

JavaScript components can get the same configuration options in 2 ways - through data attributes, as before, and now when creating an instance. These components are:

the Button component, for its preventDoubleClick option (matching data-prevent-double-click)
the CharacterCount component, for its maxlength, maxwords and threshold options (matching data-maxlength, data-maxwords and data-threshold, respectively)
the ErrorSummary component, for its disableAutoFocus option (matching data-disable-auto-focus)
the NotificationBanner component, for its disableAutoFocus option (matching data-disable-auto-focus)

You can leave out these configuration options when using the Nunjucks macro and provide configuration when:

creating a component, in a configuration object as second argument
initialising components in bulk using initAll

For example:

// Creating a single instance
var button = document.querySelector('[data-module="button"]')
new GOVUKFrontend.Button(button, {preventDoubleClick: true})

// Or initialising components in bulk
GOVUKFrontend.initAll({
  button: {
    preventDoubleClick: true
  }
  // Or, for the other components,
  // characterCount: {/* options */},
  // errorSummary: {/* options */},
  // notificationBanner: {/* options */}
})

You can find more information about component configuration in GOV.UK Frontend documentation.

This was added in pull requests specific for each components:

Recommended changes

Update the HTML for the error summary

If you're not using the Nunjucks macros, you can improve the experience for screen reader users by making these changes to the error summary markup:

Remove aria-labelledby="error-summary-title" and role="alert" from the parent element (govuk-error-summary)
Add a div wrapper around the contents of govuk-error-summary with the attribute role="alert"
Remove id="error-summary-title" from the error summary h2 (govuk-error-summary__title)

This will enable screen reader users to have a better, more coherent experience with the error summary. It will make sure users of JAWS 2022 or later will hear the entire contents of the error summary on page load and therefore have further context on why there is an error on the page they're on.

This was added in pull request #2677: Amend error summary markup to fix page load focus bug in JAWS 2022.

Deprecated features

Stop using the compatibility mode settings

In GOV.UK Frontend v5.0 we will stop supporting compatibility with legacy codebases. We are therefore deprecating the compatibility mode variables associated with legacy codebases:

$govuk-compatibility-govukfrontendtoolkit
$govuk-compatibility-govuktemplate
$govuk-compatibility-govukelements

This was introduced in pull request #2882: Deprecate compatibility mode settings.

Stop using settings associated with legacy codebases

In GOV.UK Frontend v5.0 we will stop supporting compatibility with legacy codebases. As part of this, we're deprecating settings controlled by compatibility mode variables. This includes the govuk-compatibility mixin and the following settings:

$govuk-use-legacy-palette
$govuk-use-legacy-font
$govuk-typography-use-rem
$govuk-font-family-tabular

This was introduced in pull request #2844: Remove compatibility mode from govuk-frontend.

Fixes

In pull request 2851: Support Prototype Kit v13 we've introduced support for the plugins system included in the upcoming Prototype Kit v13.

We've made fixes to GOV.UK Frontend in the following pull requests:

4.3.1

published 4.3.1 • 2 years ago

Changelog

4.3.1 (Patch release)

Recommended changes

Replace deprecated `govuk-!-margin-static` and `govuk-!-padding-static` classes

We've fixed an error in the naming convention of the static spacing override classes we'd introduced in v4.3.0. These classes should start with govuk-!-static, and we've now deprecated the incorrect classes.

If you're using the static spacing margin override classes, replace any classes starting with govuk-!-margin-static with govuk-!-static-margin. For example: govuk-!-margin-static-2 would become govuk-!-static-margin-2.

If you're using the static spacing padding override classes, replace any classes starting with govuk-!-padding-static with govuk-!-static-padding. For example: govuk-!-padding-static-2 would become govuk-!-static-padding-2.

We've deprecated the govuk-!-margin-static and govuk-!-padding-static classes, and will remove them in a future major release.

This change was introduced in pull request #2770: Fix ordering of properties in static spacing override classes. Thanks to @garrystewart for reporting this issue.

Fixes

We’ve made fixes to GOV.UK Frontend in the following pull requests:

#2766: Remove unused console.log calls from accordion JavaScript

4.3.0

published 4.3.0 • 2 years ago

Changelog

4.3.0 (Feature release)

New features

Customise the Open Graph image URL without duplicate meta tags

You can now customise the Open Graph image URL included in the head by setting the opengraphImageUrl Nunjucks option.

Also, the default Open Graph image URL meta tag will now only be included if you set the either opengraphImageUrl or assetUrl.

This was added in pull request #2673: Allow Open Graph image URL to be customised.

Localise the content licence and copyright statements

When using the footer Nunjucks macro, you can now translate the text of the Open Government Licence (OGL) and Crown copyright statements using the contentLicence and copyright parameters.

Visit The National Archives' documentation on OGL and Crown copyright for information on what you need to include in these statements.

This was added in pull request #2702: Allow localisation of content licence and copyright notices in Footer.

Pass HTML directly into compatible components

If using the Nunjucks macros, you can now pass HTML content directly into compatible components using the Nunjucks call syntax. If HTML is provided through the call syntax, the nunjucks macro will ignore the HTML and text options.

Components updated to support this syntax are:

Details
Error summary (mapped to descriptionHtml parameter)
Inset text
Notification banner
Panel

This was added in pull request #2734: Update various components to be callable.

Use new override classes to apply static spacing

You can now use static spacing override classes to apply spacing from the static spacing scale to elements of your design.

The new classes start with: govuk-!-static- followed by either margin- or padding-, and then a spacing unit number.

To apply spacing in a single direction, include left-, right-, top-, or bottom- just before the spacing unit.

For example:

govuk-!-static-margin-9 will apply a 60px margin to all sides of the element at all screen sizes
govuk-!-static-padding-right-5 will apply 25px of padding to the right side of the element at all screen sizes
govuk-!-static-margin-0 will remove all margins at all screen sizes

This was added in pull request #2672: Add static spacing override classes. Thanks to @patrickpatrickpatrick for this contribution.

Deprecated features

Remove deprecated `govuk-header__navigation--no-service-name` class in the header

We've deprecated the govuk-header__navigation--no-service-name class, and will remove it in a future major release.

This was added in pull request #2694: Deprecate .govuk-header__navigation--no-service-name.

Recommended changes

We've recently made some non-breaking changes to GOV.UK Frontend. Implementing these changes will make your service work better.

Add `hidden` to the mobile menu button in the header component

If you're not using the Nunjucks macros, add the hidden attribute to the mobile menu button in the header component. The mobile menu button is govuk-header__menu-button.

We've changed the header's mobile menu functionality to use the hidden attribute instead of using CSS to show/hide the mobile menu. Adding hidden to the mobile menu button by default will make sure that it does not display for users when javascript does not load.

This was added in pull request 2727: Make use of hidden in header navigation functionality. Thanks to @NickColley and @kr8n3r for their contributions.

Fixes

In pull request 2678: Replace ex units with ems for input lengths, we changed how we define input lengths in our CSS. Browsers might now display these inputs as being slightly wider than before. The difference is usually fewer than 3 pixels.

We’ve also made fixes in the following pull requests:

#2668: Fix Summary List action link alignment
#2670: Define minimum width for select component - thanks @Nosfistis for reporting this issue
#2723: Style accordion and tabs text content with govuk-body class
#2724: Remove redundant aria-hidden attribute from the content when using the Details polyfill
#2725: Remove padding-right from last column in summary list row - thanks @edwardhorsford for reporting this issue and suggesting a fix
#2737: Avoid unnecessary spacing-related media queries
#2747: Ensure accordion uses overriden focus colour - thanks @NickColley for reporting this issue and suggesting a fix

4.2.0

published 4.2.0 • 2 years ago

Changelog

4.2.0 (Feature release)

New features

Help users navigate through pages with pagination

You can now use pagination to help users navigate forwards and backwards through a series of pages. For example, in search results or guidance that's divided into multiple website pages.

This was added in pull request #2610: Add pagination component.

Check checkboxes by using the `values` Nunjucks option

When using the govukCheckboxes Nunjucks macro, you can now use the values option to determine which checkboxes should already be checked when the page loads.

For example, values: ['red', 'blue'] would check any checkboxes that have a value of 'red' or 'blue'.

You can use this option instead of setting the boolean checked option on each individual checkbox.

This change was introduced in pull request #2616: Allow selecting options by passing current values.

Check a radio button by using the `value` Nunjucks option

When using the govukRadios Nunjucks macro, you can now use the value option to determine which radio should already be checked when the page loads.

For example, value: 'red' would check the radio that has a value of 'red'.

You can use this option instead of setting the boolean checked option on each individual radio.

This change was introduced in pull request #2616: Allow selecting options by passing current values.

Select an option in a select by using the `value` Nunjucks option

When using the govukSelect Nunjucks macro, you can now use the value option to determine which option should already be selected when the page loads.

For example, value: 'red' would select the option that has a value of 'red'.

You can use this option instead of setting the boolean selected option on each individual option.

This change was introduced in pull request #2616: Allow selecting options by passing current values.

Recommended changes

Replace deprecated `govuk-header__link--service-name` class in the header

If you're not using the Nunjucks macros in the header, replace any instances of the class govuk-header__link--service-name with govuk-header__service-name.

We've deprecated the govuk-header__link--service-name class, and will remove it in a future major release.

This change was introduced in pull request #2617: Do not make the service name in the header a link if no serviceUrl is provided.

File extensions added for JavaScript ES Module imports

We have updated our component ES module JavaScript to include missing file extensions not provided in release 4.1.0. If you have received an error similar to the following, for example when running or building your application, this fix should resolve the issue.

Cannot find module '../node_modules/govuk-frontend/govuk-esm/common' imported from ../node_modules/govuk-frontend/govuk-esm/all.mjs

You should not need to make any changes if you are successfully importing our JavaScript as ES modules with version 4.1.0, but there still might be config you can remove. For example, removing fullySpecified: false from your Webpack config file.

This change was introduced in pull request #2658: Add missing mandatory file extensions for ESM JavaScript. Thanks to @colinrotherham and @tvararu for reporting issues and suggesting and testing fixes.

Fixes

We’ve made fixes to GOV.UK Frontend in the following pull requests:

#2617: Do not make the service name in the header a link if no serviceUrl is provided
#2640: Add top padding to accordion section
#2644: Allow users to use require.resolve to import GOV.UK Frontend JavaScript - thanks to @HughePaul for reporting this issue and testing the fix
#2647: Allow users to import sass files via Webpack sass-loader - thanks to @Garethp for reporting this issue, and to @Garethp and @richpjames for testing the fix
#2659: Add missing label and legend classes to HTML fixtures

4.1.0

published 4.1.0 • 2 years ago

Changelog

4.1.0 (Feature release)

New features

4.0.1

published 4.0.1 • 3 years ago

Changelog

4.0.1 (Fix release)

Recommended changes

We've recently made some non-breaking changes to GOV.UK Frontend. Implementing these changes will make your service work better.

Remove the `tabindex` attribute from the error summary component

If you're not using Nunjucks macros, remove the tabindex attribute from the error summary's HTML. The component JavaScript now adds and removes this attribute.

This change was introduced in pull request #2491: Prevent error summary from being refocused after it has been initially focused on page load.

Fixes

We’ve made fixes to GOV.UK Frontend in the following pull requests:

4.0.0

published 4.0.0 • 3 years ago

Changelog

4.0.0 (Breaking release)

Breaking changes

This release contains a lot of breaking changes, but we expect many of them will only affect a small number of users. However, to make sure your service still works after you upgrade, you should read the release notes and make any required changes.

Check your accordions still display as expected

We've changed the design of the accordion. You can see its new look and read the revised guidance, particularly about when and when not to use accordions.

You should check your accordions still display as expected if you have any:

accordions with custom styles
section headings that contain unusual formatting (for example, wrappers)

You do not need to make changes to the content that accordions hide or show, as this release's changes do not affect it.

These changes were introduced in pull request #2257: Update accordion design. Thanks to Mia Allers, Owen Jones, Nikin Nagewadia and Chris Yoong for their contributions.

Only use the accordion’s summary line for ‘phrasing content’

The summary line is now inside the HTML button element, so you can only add 'phrasing content' to it. Do not use any non-phrasing content, as the resulting HTML will not be valid.

This change was introduced in pull request #2257: Update accordion design.

Review and revise the accordion's summary line content

Only add a summary line if you need to, as it's likely to make the button text too long.

If you're already using the summary line, review your use of the summary line to make sure you actually need it.

If you need to keep the summary line, review the accordion guidance and make the summary line as short as possible.

Update the HTML for summary lists

We've updated the HTML for the summary list component to avoid nesting <span> elements within <dd> elements, which is invalid HTML. This update only affects you if you have summary lists that include a mix of rows with and without actions. You can read more about adding actions to rows.

If you're not using Nunjucks macros, do not include an empty <span class="govuk-summary-list__actions"></span> in rows without actions. Instead, add the govuk-summary-list__row--no-actions modifier class to the row.

This change was introduced in pull request #2323: Avoid invalid nesting of <span> within a <dd> in summary list. Thanks to Malcolm Hire for reporting this issue.

Update the HTML for navigation in the header

We've updated the HTML for the header. This update only affects you if your header includes navigation.

Any additional classes passed using the navigationClasses Nunjucks option are now applied to the <nav> rather than the <ul>. Check the additional classes are still doing what you expect.

If you're not using Nunjucks macros, then you should:

move the <button> inside the <nav>, immediately before the <ul>
move the aria-label attribute from the <ul> to the <nav>
move the govuk-header__navigation class from the <ul> to the <nav>
add the govuk-header__navigation-list class to the <ul>

Check your changes against the header example in the Design System to make sure you have correctly implemented them.

This change was introduced in pull request #2427: Improve the screen reader experience for the header menu.

Style any custom HTML in your cookie banner

We've removed the default font styles from the cookie banner Sass. This change makes it more obvious when you have not added classes and styles to any custom HTML.

If you're passing custom HTML into the cookie banner component (for example, using the html Nunjucks parameter), you must make sure you're applying the appropriate classes and styles to that HTML. This could look like, for example, adding the govuk-body class to any paragraph tags. You must do this to prevent your cookie banner displaying with unstyled text.

This change was introduced in pull request #2432: Remove default font styles from cookie banner Sass.

Update the HTML for hints

In GOV.UK Frontend v3.8.0, we updated the HTML for hints to use a <div> rather than a <span> element, to allow the use of block elements. We've now removed the styles which made the hint <span> display as block.

If you’re not using Nunjucks macros, update your hint HTML to use a <div> rather than a <span>. For example: <div id="input-hint" class="govuk-hint"></div> instead of <span id="input-hint" class="govuk-hint"></span>.

This change was introduced in pull request #2437: Remove display:block on hint component.

Include JavaScript for skip link to improve screen reader announcements

We've added JavaScript for the skip link component to set focus to the linked element, for example, the main content on the page. This helps screen readers read the linked content when users use the skip link component.

If you're importing JavaScript for individual components, import the skip link JavaScript.

If you're not using Nunjucks macros, add a data-module="govuk-skip-link" attribute to the component HTML. For example:

<div class="govuk-skip-link" data-module="govuk-skip-link">
...
</div>

Once you've made the changes, check the skip link JavaScript works. To do this, select the skip link and check the linked element (usually the <main> element) in the browser has a tabindex attribute.

This change was introduced in pull request #2450: Set focus to skip link target to improve screen reader announcements.

Update the HTML for error messages

We’ve updated the HTML for the error message component to use a <p> element instead of a <span> element, as this is more semantically correct.

If you’re not using Nunjucks macros, swap the <span class="govuk-error-message"> for a <p class="govuk-error-message">.

This change was introduced in pull request #2452: Update error messages to use paragraph tags instead of spans.

Check components that conditionally reveal content still work

On radios and checkboxes, the JavaScript now looks within the whole page for conditionally-revealed content. Before, it only looked within the same set of radios or checkboxes.

If you see unexpected behaviour, make sure the revealed content's id is unique within the page the content is on. Reusing the same id within a page could cause a radio or checkbox to reveal or hide the wrong element, and also means your HTML is invalid.

This change was introduced in pull request #2370: Prevent issues with conditionally revealed content when content id includes CSS syntax characters.

Check the character count component still works as expected

On character counts, the JavaScript now looks within the whole page for the count message, which will be something similar to “You have 200 characters remaining”. Before, it only looked within the character count component.

If you see unexpected behaviour, make sure the id for the textarea component is unique within the page the content is on. Reusing the same id within a page could cause the wrong count message to update, and also means your HTML is invalid.

This change was introduced in pull request #2408: Prevent issues with character count when textarea id includes CSS syntax characters.

Check individually-imported JavaScript modules work as expected

You do not need to do anything if you have done at least one of the following:

followed our Getting Started guide and are importing all of the GOV.UK Frontend JavaScript in one go via all.js
installed GOV.UK Frontend using precompiled files

We've changed the naming of our components' JavaScript modules so individual imports are now attached to window.GOVUKFrontend.[ComponentName] instead of window.GOVUKFrontend.

You can now import multiple modules without overwriting the previous one, for example:

//= require govuk/components/accordion/accordion.js
//= require govuk/components/button/button.js

3.14.0

published 3.14.0 • 3 years ago

Changelog