How to guides

Extending and modifying components in production

You might need to extend or modify components in the GOV.UK Design System from time to time. For example to:

  • improve them based on user research
  • meet a specific user need in your service

Consider whether your changes:

  • help the long term maintenance of your service
  • allow you to safely install updates from the GOV.UK Design System
  • reduce the risk of technical debt

When you extend or modify components in the GOV.UK Design System you create potential risk. For example, your code or service may break when you install Design System updates.

You can help reduce potential risk to your code by:

The GOV.UK Design System team uses many of these techniques to make sure code in the GOV.UK Design System does not unintentionally break your application code.

Start with override classes

Check the styles section to see if there’s a CSS class you can use before adding CSS to your service.

For example, you can make changes to:

Avoid overwriting GOV.UK Design System code

If you make a modification involving CSS you might decide to write a selector that targets a GOV.UK Design System class and change its CSS properties.

This will work in the short term but may break if you install an update relying on the component’s previous behaviour.

For example, if you want to override the button component you could do the following.

<div class="app-interruption-card">
  <button class="govuk-button">
    Inverse button
  </button>
</div>

.app-interruption-card .govuk-button {
  background-color: white;
  color: blue;
}

This would work in the short term, but if the GOV.UK Design System team changes how the button component works it could break when you update your service. For examples like this, consider using small modifications to components.

Use a unique prefix for component names

The GOV.UK Design System team uses prefixes, sometimes called namespacing, to make sure the code in the GOV.UK Design System does not unintentionally break your application code.

Styles, components and patterns in the GOV.UK Design System use the govuk- prefix.

When writing code for your application, use a different prefix, like app-.

If your department has its own design resources, they should use a new separate prefix. It’s a good idea to use departmental initials, like hmcts- or dvla-.

Apply this principle anywhere you name components, such as to:

  • CSS class names
  • Nunjucks Macros
  • SCSS variables and mixins

If you contribute a component from an app to a departmental design system or the GOV.UK Design System, change the component’s prefix accordingly.

Custom override classes

If you need to specify some custom override classes which do not belong to a particular component, you can define these using your prefix and the -!- convention from the GOV.UK Design System.

For example, to define a custom width for a specific reference number in your services you might do this.

.app-\!-reference-number-width {
  width: 10ch !important;
}

<span class="app-!-reference-number-width">
  7446868939
</span>

Small modifications to components

The GOV.UK Design System uses a naming convention called Block Element Modifier (BEM) which makes it easier to ensure styling is isolated to individual components. You can use this convention to make modifications to components.

When making small modifications to components you can make use of the modifier convention from BEM, which uses a suffix of -- plus a name, alongside your own prefix.

For example, if you wanted to override the button component you could do the following.

<div class="app-interruption-card">
  <button class="govuk-button app-button--inverse">
    Inverse button
  </button>
</div>

.app-button--inverse {
  background-color: govuk-colour("white");
  color: govuk-colour("blue");
}

You should not use modifiers when:

  • you’re modifying most of the component
  • the component does not meet the original user need
  • you need to make large changes to the HTML markup

Large modifications to components

If you need to make a large modification to a component you should fork it entirely by copying and pasting the source code to create a new component.

When you do this you’ll need to rename all prefixes that include govuk to avoid conflicts. You should also use a different component name from those already in the GOV.UK Design System, to differentiate your unique component from a BEM modifier.

Doing this removes the possibility of any updates breaking your service. However, you will not receive any future updates from the original component.

For example, a large modification of an existing component is the step by step navigation which began as a small modification to the accordion component. The step by step navigation had so many changes it was eventually forked into a separate component.

Contributing back

If you’ve extended something and you think it’s useful for the wider government community you can propose an improvement.

You can do this by proposing your change to a component on the list of discussions on GitHub.

Need help?

If you’ve got a question about the GOV.UK Design System, contact the team.