Version 5.0.0

Release notes

⚠️ This is a breaking change release

Version 5.0.0 of the ruby govuk-components gem supports version 5.0.0 of the govuk-frontend npm package. Both contain breaking changes, and are dependent on each other – so you should update both at the same time.

These release notes for the ruby gem should be read alongside the release notes for govuk-frontend.

Upgrade instructions

1. Install both the gem AND the node package

Update the version of govuk-component in your Gemfile and run bundle install:

gem "govuk-components", "~> 5.0.0"

Update your version of govuk-frontend in your package.json and then run npm install or yarn install (depending on which you use).

"govuk-frontend": "5.0.0",

2. Check that your app still builds

The way that assets have been packaged in govuk-frontend has changed, so you may need to update your build process.

If you're using Sass, change

@import "govuk-frontend/govuk/all";

to

@import "govuk-frontend/dist/govuk/all";

If you are using a javascript compiler, change govuk-frontend/govuk to govuk-frontend/dist/govuk.

See release notes for govuk-frontend 5.0.0 for details.

3. Update your application layout file

In your application layout file (normally layouts/application.html.erb), update the code snippet which adds a class to the document body.

Update it from this:

<script>document.body.className = ((document.body.className) ? document.body.className + ' js-enabled' : 'js-enabled');</script>

to this:

<script>document.body.className += ' js-enabled' + ('noModule' in HTMLScriptElement.prototype ? ' govuk-frontend-supported' : '');</script>

Once this is done, things like accordions and conditionally-revealing form elements should work as before.

4. Update any links using controller and action references

Replace any links using the old { controller: "abc", action: "xyz" } style arguments with links that use route helpers. Change

govuk_link_to("Peanuts", controller: "snacks", action: "show", id: "peanuts")

to

govuk_link_to("Peanuts", snack_path("peanuts"))

5. Check capitalisation of any tag components

The Tag component no longer uses CSS to make the text UPPERCASE.

If you use any tags, check that the text has an initial capital letter only in the HTML.

The colours have also changed, so check they still have sufficient contrast against any background.

6. Check the logo in the header

The way the GOV.UK logo is rendered within an SVG image has changed.

If you are using the govuk_header component, there should be no need for any further changes unless you previously set custom logotype text. This is no longer supported. If you need to change the logo, you should set the custom_logo slot within the header component instead.

7. Update asset pipeline

If you use Rails’s asset pipeline to import the images and fonts from govuk-frontend, you’ll need to add the dist folder to the path.

Within config/initalizers/assets.rb, change this:

Rails.application.config.assets.paths << Rails.root.join("node_modules/govuk-frontend/govuk/assets/images")
Rails.application.config.assets.paths << Rails.root.join("node_modules/govuk-frontend/govuk/assets/fonts")

to this:

Rails.application.config.assets.paths << Rails.root.join("node_modules/govuk-frontend/dist/govuk/assets/images")
Rails.application.config.assets.paths << Rails.root.join("node_modules/govuk-frontend/dist/gov/assets/fonts")

If you use sprockets to compile javascript or CSS, update the path in the manifest.

Within app/assets/config/manifest.js, change this:

//= link_directory ../../../node_modules/govuk-frontend/govuk/assets/images
//= link_directory ../../../node_modules/govuk-frontend/govuk/assets/fonts

to this:

//= link_directory ../../../node_modules/govuk-frontend/dist/govuk/assets/images
//= link_directory ../../../node_modules/govuk-frontend/dist/govuk/assets/fonts

8. Update favicon references in your application layout file

The included icons within govuk-frontend have been updated, with some of the old ones removed.

Within your layouts/application.html.erb layout file, change these lines:

    <%= favicon_link_tag image_path('favicon.ico') %>
    <%= favicon_link_tag image_path('govuk-mask-icon.svg'), rel: 'mask-icon', type: 'image/svg', color: "#0b0c0c" %>
    <%= favicon_link_tag image_path('govuk-apple-touch-icon.png'), rel: 'apple-touch-icon', type: 'image/png' %>
    <%= favicon_link_tag image_path('govuk-apple-touch-icon-152x152.png'), rel: 'apple-touch-icon', type: 'image/png', size: '152x152' %>
    <%= favicon_link_tag image_path('govuk-apple-touch-icon-167x167.png'), rel: 'apple-touch-icon', type: 'image/png', size: '167x167' %>
    <%= favicon_link_tag image_path('govuk-apple-touch-icon-180x180.png'), rel: 'apple-touch-icon', type: 'image/png', size: '180x180' %>

to this:

    <%= favicon_link_tag image_path('favicon.ico'), type: nil, sizes: "48x48" %>
    <%= favicon_link_tag image_path('favicon.svg'), type: 'image/svg+xml', sizes: "any" %>
    <%= favicon_link_tag image_path('govuk-icon-mask.svg'), rel: 'mask-icon', color: "#0b0c0c", type: nil %>
    <%= favicon_link_tag image_path('govuk-icon-180.png'), rel: 'apple-touch-icon', type: nil %>

New features

Task list

The gem now supports the new Task list component within govuk-frontend.

If your service features a task list, you can take advantage of this by swapping out your custom task list code for the govuk_task_list component.

Here’s an example of how this can be used:

 <%= govuk_task_list(id_prefix: "coloured-tags-example") do |task_list| %>
   <% task_list.with_item(
      title: "Design", 
      href: "#", 
      status: govuk_tag(text: "Green", colour: "green")
    ) %>
 <% end %>

New link helpers

The following helpers: #govuk_link_to, #govuk_button_link_to, #govuk_button_to and #govuk_mail_to, plus the class helpers #govuk_link_classes and #govuk_button_classes have been rewritten to use keyword arguments instead of trying to juggle the arguments based on what's passed in, like the old Rails-style ones.

This is a breaking change because the new implementations don't support all the features the Rails ones do,
mainly that govuk_link_to("Peanuts", controller: "snacks", action: "show", id: "peanuts") style invocation won't work. The Rails documentation has advised against using this form of link for many years - pass in the path instead, i.e.,govuk_link_to("Peanuts", snack_path("peanuts"))

The new helpers allow us to easily add extra GOV.UK specific arguments, these include:

• new_tab: true - open the page in a new tab, adds rel="noreferrer noopener" and target="_blank" automatically to links #419
• visually_hidden_prefix and visually_hidden_suffix - add .govuk-visually-hidden text before or after the link text #465

If you don't want to upgrade and continue using the old style link helpers for now, manually include GovukRailsCompatibleLinkHelper.

Visually hidden helper

There's a new helper called govuk_visually_hidden which takes either a text argument or a block of HTML and wraps it in <span class="govuk-visually-hidden">.

<%= govuk_visually_hidden("This text won't appear on the page but will be read out by a screenreader") %>

Thank you

A massive thanks to @frankieroberto for his work on this release, and to @colinrotherham for reviewing the changes