Components

Tag

Use the tag component to show users the status of something.

WCAG 2.2

New WCAG 2.2 criteria affect this component

To use the ‘Tag’ and meet the new Web Content Accessibility Guidelines (WCAG) 2.2 criteria, make sure that users can successfully:

See the full list of components and patterns affected by WCAG 2.2.

<strong class="govuk-tag">
  Completed
</strong>
Nunjucks macro options

Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.

Some options are required for the macro to work; these are marked as “Required” in the option description.

If you’re using Nunjucks macros in production with “html” options, or ones ending with “html”, you must sanitise the HTML to protect against cross-site scripting exploits.

Primary options
Name Type Description
text string Required. If html is set, this is not required. Text to use within the tag component. If html is provided, the text option will be ignored.
html string Required. If text is set, this is not required. HTML to use within the tag component. If html is provided, the text option will be ignored.
classes string Classes to add to the tag.
attributes object HTML attributes (for example data attributes) to add to the tag.
{%- from "govuk/components/tag/macro.njk" import govukTag -%}

{{ govukTag({
  text: "Completed"
}) }}

When to use this component

Use the tag component when it’s possible for something to have more than one status and it’s useful for the user to know about that status. For example, you can use a tag to show whether an item in a task list has been ‘completed’.

How it works

There are two ways to use the tag component. You can use HTML or, if you are using Nunjucks or the GOV.UK Prototype Kit, you can use the Nunjucks macro.

Tags are only used to indicate a status. Do not make a tag interactive by making it into a link or button. Use adjectives (descriptive words) and not verbs (action words) for the names of your tags. Using a verb might make a user think that clicking on them will do something.

Do not use tags to create links, buttons or other interactive elements, as users:

  • are unlikely to identify the tags as something they’re meant to interact with
  • would see no visual difference between interactive and non-interactive tags

Showing one or two statuses

Sometimes a single status is enough. For example if you need to tell users which parts of an application they’ve finished and which they have not, you may only need a ‘Completed’ tag. Because the user understands that if something does not have a tag, that means it’s incomplete.

The complete multiple tasks pattern has an example of how to show one status using tags.

Or it can make sense to have two statuses. For example you may find that there’s a need to have one tag for ‘Active’ users and one for ‘Inactive’ users.

<table class="govuk-table">
  <thead class="govuk-table__head">
    <tr class="govuk-table__row">
      <th class="govuk-table__header" scope="col"> Name of user </th>
      <th class="govuk-table__header" scope="col"> Status </th>
    </tr>
  </thead>
  <tbody class="govuk-table__body">
    <tr class="govuk-table__row">
      <td class="govuk-table__cell">
        Rachel Silver
      </td>
      <td class="govuk-table__cell">
        <strong class="govuk-tag govuk-tag--grey">
          Inactive
        </strong>
      </td>
    </tr>
    <tr class="govuk-table__row">
      <td class="govuk-table__cell">
        Jesse Smith
      </td>
      <td class="govuk-table__cell">
        <strong class="govuk-tag govuk-tag--grey">
          Inactive
        </strong>
      </td>
    </tr>
    <tr class="govuk-table__row">
      <td class="govuk-table__cell">
        Joshua Wessel
      </td>
      <td class="govuk-table__cell">
        <strong class="govuk-tag">
          Active
        </strong>
      </td>
    </tr>
    <tr class="govuk-table__row">
      <td class="govuk-table__cell">
        Rachael Pepper
      </td>
      <td class="govuk-table__cell">
        <strong class="govuk-tag">
          Active
        </strong>
      </td>
    </tr>
    <tr class="govuk-table__row">
      <td class="govuk-table__cell">
        Stuart Say
      </td>
      <td class="govuk-table__cell">
        <strong class="govuk-tag govuk-tag--grey">
          Inactive
        </strong>
      </td>
    </tr>
    <tr class="govuk-table__row">
      <td class="govuk-table__cell">
        Laura Frith
      </td>
      <td class="govuk-table__cell">
        <strong class="govuk-tag">
          Active
        </strong>
      </td>
    </tr>
    <tr class="govuk-table__row">
      <td class="govuk-table__cell">
        Tim Harvey
      </td>
      <td class="govuk-table__cell">
        <strong class="govuk-tag govuk-tag--grey">
          Inactive
        </strong>
      </td>
    </tr>
  </tbody>
</table>
Nunjucks macro options

Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.

Some options are required for the macro to work; these are marked as “Required” in the option description.

If you’re using Nunjucks macros in production with “html” options, or ones ending with “html”, you must sanitise the HTML to protect against cross-site scripting exploits.

Primary options
Name Type Description
text string Required. If html is set, this is not required. Text to use within the tag component. If html is provided, the text option will be ignored.
html string Required. If text is set, this is not required. HTML to use within the tag component. If html is provided, the text option will be ignored.
classes string Classes to add to the tag.
attributes object HTML attributes (for example data attributes) to add to the tag.
{%- from "govuk/components/tag/macro.njk" import govukTag -%}

<table class="govuk-table">
  <thead class="govuk-table__head">
    <tr class="govuk-table__row">
      <th class="govuk-table__header" scope="col"> Name of user </th>
      <th class="govuk-table__header" scope="col"> Status </th>
    </tr>
  </thead>
  <tbody class="govuk-table__body">
    <tr class="govuk-table__row">
      <td class="govuk-table__cell">
        Rachel Silver
      </td>
      <td class="govuk-table__cell">
        {{govukTag({
          text: "Inactive",
          classes: "govuk-tag--grey"
        })}}
      </td>
    </tr>
    <tr class="govuk-table__row">
      <td class="govuk-table__cell">
        Jesse Smith
      </td>
      <td class="govuk-table__cell">
        {{govukTag({
          text: "Inactive",
          classes: "govuk-tag--grey"
        })}}
      </td>
    </tr>
    <tr class="govuk-table__row">
      <td class="govuk-table__cell">
        Joshua Wessel
      </td>
      <td class="govuk-table__cell">
        {{govukTag({
          text: "Active"
        })}}
      </td>
    </tr>
    <tr class="govuk-table__row">
      <td class="govuk-table__cell">
        Rachael Pepper
      </td>
      <td class="govuk-table__cell">
        {{govukTag({
          text: "Active"
        })}}
      </td>
    </tr>
    <tr class="govuk-table__row">
      <td class="govuk-table__cell">
        Stuart Say
      </td>
      <td class="govuk-table__cell">
        {{govukTag({
          text: "Inactive",
          classes: "govuk-tag--grey"
        })}}
      </td>
    </tr>
    <tr class="govuk-table__row">
      <td class="govuk-table__cell">
        Laura Frith
      </td>
      <td class="govuk-table__cell">
        {{govukTag({
          text: "Active"
        })}}
      </td>
    </tr>
    <tr class="govuk-table__row">
      <td class="govuk-table__cell">
        Tim Harvey
      </td>
      <td class="govuk-table__cell">
        {{govukTag({
          text: "Inactive",
          classes: "govuk-tag--grey"
        })}}
      </td>
    </tr>
  </tbody>
</table>

Showing multiple statuses

Tags should be helpful to users. The more you add, the harder it is for users to remember them. So start with the smallest number of statuses you think might work, then add more if your user research shows there’s a need for them.

<table class="govuk-table">
  <thead class="govuk-table__head">
    <tr class="govuk-table__row">
      <th class="govuk-table__header" scope="col"> Application </th>
      <th class="govuk-table__header" scope="col"> Status </th>
    </tr>
  </thead>
  <tbody class="govuk-table__body">
    <tr class="govuk-table__row">
      <td class="govuk-table__cell">
        Joshua Wessel
      </td>
      <td class="govuk-table__cell">
        <strong class="govuk-tag govuk-tag--red">
          Urgent
        </strong>
      </td>
    </tr>
    <tr class="govuk-table__row">
      <td class="govuk-table__cell">
        Rachel Silver
      </td>
      <td class="govuk-table__cell">
        <strong class="govuk-tag govuk-tag--blue">
          New
        </strong>
      </td>
    </tr>
    <tr class="govuk-table__row">
      <td class="govuk-table__cell">
        Laura Frith
      </td>
      <td class="govuk-table__cell">
        <strong class="govuk-tag govuk-tag--blue">
          New
        </strong>
      </td>
    </tr>
    <tr class="govuk-table__row">
      <td class="govuk-table__cell">
        Paul French
      </td>
      <td class="govuk-table__cell">
        <strong class="govuk-tag govuk-tag--blue">
          New
        </strong>
      </td>
    </tr>
    <tr class="govuk-table__row">
      <td class="govuk-table__cell">
        Jesse Smith
      </td>
      <td class="govuk-table__cell">
        <strong class="govuk-tag govuk-tag--blue">
          New
        </strong>
      </td>
    </tr>
    <tr class="govuk-table__row">
      <td class="govuk-table__cell">
        Rachael Pepper
      </td>
      <td class="govuk-table__cell">
        <strong class="govuk-tag govuk-tag--green">
          Finished
        </strong>
      </td>
    </tr>
    <tr class="govuk-table__row">
      <td class="govuk-table__cell">
        Emma Tennant
      </td>
      <td class="govuk-table__cell">
        <strong class="govuk-tag govuk-tag--yellow">
          Waiting on
        </strong>
      </td>
    </tr>
  </tbody>
</table>
Nunjucks macro options

Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.

Some options are required for the macro to work; these are marked as “Required” in the option description.

If you’re using Nunjucks macros in production with “html” options, or ones ending with “html”, you must sanitise the HTML to protect against cross-site scripting exploits.

Primary options
Name Type Description
text string Required. If html is set, this is not required. Text to use within the tag component. If html is provided, the text option will be ignored.
html string Required. If text is set, this is not required. HTML to use within the tag component. If html is provided, the text option will be ignored.
classes string Classes to add to the tag.
attributes object HTML attributes (for example data attributes) to add to the tag.
{%- from "govuk/components/tag/macro.njk" import govukTag -%}

<table class="govuk-table">
  <thead class="govuk-table__head">
    <tr class="govuk-table__row">
      <th class="govuk-table__header" scope="col"> Application </th>
      <th class="govuk-table__header" scope="col"> Status </th>
    </tr>
  </thead>
  <tbody class="govuk-table__body">
    <tr class="govuk-table__row">
      <td class="govuk-table__cell">
        Joshua Wessel
      </td>
      <td class="govuk-table__cell">
        {{govukTag({
          text: "Urgent",
          classes: "govuk-tag--red"
        })}}
      </td>
    </tr>
    <tr class="govuk-table__row">
      <td class="govuk-table__cell">
        Rachel Silver
      </td>
      <td class="govuk-table__cell">
        {{govukTag({
          text: "New",
          classes: "govuk-tag--blue"
        })}}
      </td>
    </tr>
    <tr class="govuk-table__row">
      <td class="govuk-table__cell">
        Laura Frith
      </td>
      <td class="govuk-table__cell">
        {{govukTag({
          text: "New",
          classes: "govuk-tag--blue"
        })}}
      </td>
    </tr>
    <tr class="govuk-table__row">
      <td class="govuk-table__cell">
        Paul French
      </td>
      <td class="govuk-table__cell">
        {{govukTag({
          text: "New",
          classes: "govuk-tag--blue"
        })}}
      </td>
    </tr>
    <tr class="govuk-table__row">
      <td class="govuk-table__cell">
        Jesse Smith
      </td>
      <td class="govuk-table__cell">
        {{govukTag({
          text: "New",
          classes: "govuk-tag--blue"
        })}}
      </td>
    </tr>
    <tr class="govuk-table__row">
      <td class="govuk-table__cell">
        Rachael Pepper
      </td>
      <td class="govuk-table__cell">
        {{govukTag({
          text: "Finished",
          classes: "govuk-tag--green"
        })}}
      </td>
    </tr>

    <tr class="govuk-table__row">
      <td class="govuk-table__cell">
        Emma Tennant
      </td>
      <td class="govuk-table__cell">
        {{govukTag({
          text: "Waiting on",
          classes: "govuk-tag--yellow"
        })}}
      </td>
    </tr>
  </tbody>
</table>
WCAG 2.2

Any tag implementation that allows the user to change the order of tags must offer a way to do so without relying on ‘click and drag’ movements. This is to comply with WCAG 2.2 success criterion 2.5.7 Dragging movements.

Using colour with tags

You can use colour to help distinguish between different tags – or to help draw the user’s attention to a tag if it’s especially important. For example, it probably makes sense to use govuk-tag--red for a tag that reads ‘Urgent’.

Do not use colour alone to convey information because it’s not accessible. If you use the same tag in more than one place, make sure you keep the colour consistent.

Additional colours

If you need more tag colours, you can use the following colours.

<table class="govuk-table">
  <thead class="govuk-table__head">
    <tr class="govuk-table__row">
      <th class="govuk-table__header" scope="col"> Class name </th>
      <th class="govuk-table__header" scope="col"> Tag </th>
    </tr>
  </thead>
  <tbody class="govuk-table__body">
    <tr class="govuk-table__row">
      <td class="govuk-table__cell">
        <code> govuk-tag--grey </code>
      </td>
      <td class="govuk-table__cell">
        <strong class="govuk-tag govuk-tag--grey">
          Inactive
        </strong>
      </td>
    </tr>
    <tr class="govuk-table__row">
      <td class="govuk-table__cell">
        <code> govuk-tag--green </code>
      </td>
      <td class="govuk-table__cell">
        <strong class="govuk-tag govuk-tag--green">
          New
        </strong>
      </td>
    </tr>
    <tr class="govuk-table__row">
      <td class="govuk-table__cell">
        <code> govuk-tag--turquoise </code>
      </td>
      <td class="govuk-table__cell">
        <strong class="govuk-tag govuk-tag--turquoise">
          Active
        </strong>
      </td>
    </tr>
    <tr class="govuk-table__row">
      <td class="govuk-table__cell">
        <code> govuk-tag--blue </code>
      </td>
      <td class="govuk-table__cell">
        <strong class="govuk-tag govuk-tag--blue">
          Pending
        </strong>
      </td>
    </tr>
    <tr class="govuk-table__row">
      <td class="govuk-table__cell">
        <code> govuk-tag--light-blue </code>
      </td>
      <td class="govuk-table__cell">
        <strong class="govuk-tag govuk-tag--light-blue">
          In progress
        </strong>
      </td>
    </tr>
    <tr class="govuk-table__row">
      <td class="govuk-table__cell">
        <code> govuk-tag--purple </code>
      </td>
      <td class="govuk-table__cell">
        <strong class="govuk-tag govuk-tag--purple">
          Received
        </strong>
      </td>
    </tr>
    <tr class="govuk-table__row">
      <td class="govuk-table__cell">
        <code> govuk-tag--pink </code>
      </td>
      <td class="govuk-table__cell">
        <strong class="govuk-tag govuk-tag--pink">
          Sent
        </strong>
      </td>
    </tr>
    <tr class="govuk-table__row">
      <td class="govuk-table__cell">
        <code> govuk-tag--red </code>
      </td>
      <td class="govuk-table__cell">
        <strong class="govuk-tag govuk-tag--red">
          Rejected
        </strong>
      </td>
    </tr>
    <tr class="govuk-table__row">
      <td class="govuk-table__cell">
        <code> govuk-tag--orange </code>
      </td>
      <td class="govuk-table__cell">
        <strong class="govuk-tag govuk-tag--orange">
          Declined
        </strong>
      </td>
    </tr>
    <tr class="govuk-table__row">
      <td class="govuk-table__cell">
        <code> govuk-tag--yellow </code>
      </td>
      <td class="govuk-table__cell">
        <strong class="govuk-tag govuk-tag--yellow">
          Delayed
        </strong>
      </td>
    </tr>
  </tbody>
</table>
Nunjucks macro options

Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.

Some options are required for the macro to work; these are marked as “Required” in the option description.

If you’re using Nunjucks macros in production with “html” options, or ones ending with “html”, you must sanitise the HTML to protect against cross-site scripting exploits.

Primary options
Name Type Description
text string Required. If html is set, this is not required. Text to use within the tag component. If html is provided, the text option will be ignored.
html string Required. If text is set, this is not required. HTML to use within the tag component. If html is provided, the text option will be ignored.
classes string Classes to add to the tag.
attributes object HTML attributes (for example data attributes) to add to the tag.
{%- from "govuk/components/tag/macro.njk" import govukTag -%}

<table class="govuk-table">
  <thead class="govuk-table__head">
    <tr class="govuk-table__row">
      <th class="govuk-table__header" scope="col"> Class name </th>
      <th class="govuk-table__header" scope="col"> Tag </th>
    </tr>
  </thead>
  <tbody class="govuk-table__body">
    <tr class="govuk-table__row">
      <td class="govuk-table__cell">
        <code> govuk-tag--grey </code>
      </td>
      <td class="govuk-table__cell">
        {{govukTag({
          text: "Inactive",
          classes: "govuk-tag--grey"
        })}}
      </td>
    </tr>
    <tr class="govuk-table__row">
      <td class="govuk-table__cell">
        <code> govuk-tag--green </code>
      </td>
      <td class="govuk-table__cell">
        {{govukTag({
          text: "New",
          classes: "govuk-tag--green"
        })}}
      </td>
    </tr>
    <tr class="govuk-table__row">
      <td class="govuk-table__cell">
        <code> govuk-tag--turquoise </code>
      </td>
      <td class="govuk-table__cell">
        {{govukTag({
          text: "Active",
          classes: "govuk-tag--turquoise"
        })}}
      </td>
    </tr>
    <tr class="govuk-table__row">
      <td class="govuk-table__cell">
        <code> govuk-tag--blue </code>
      </td>
      <td class="govuk-table__cell">
        {{govukTag({
          text: "Pending",
          classes: "govuk-tag--blue"
        })}}
      </td>
    </tr>
    <tr class="govuk-table__row">
      <td class="govuk-table__cell">
        <code> govuk-tag--light-blue </code>
      </td>
      <td class="govuk-table__cell">
        {{ govukTag({
          text: "In progress",
          classes: "govuk-tag--light-blue"
        }) }}
      </td>
    </tr>
    <tr class="govuk-table__row">
      <td class="govuk-table__cell">
        <code> govuk-tag--purple </code>
      </td>
      <td class="govuk-table__cell">
        {{govukTag({
          text: "Received",
          classes: "govuk-tag--purple"
        })}}
      </td>
    </tr>
    <tr class="govuk-table__row">
      <td class="govuk-table__cell">
        <code> govuk-tag--pink </code>
      </td>
      <td class="govuk-table__cell">
        {{govukTag({
          text: "Sent",
          classes: "govuk-tag--pink"
        })}}
      </td>
    </tr>
    <tr class="govuk-table__row">
      <td class="govuk-table__cell">
        <code> govuk-tag--red </code>
      </td>
      <td class="govuk-table__cell">
        {{govukTag({
          text: "Rejected",
          classes: "govuk-tag--red"
        })}}
      </td>
    </tr>
    <tr class="govuk-table__row">
      <td class="govuk-table__cell">
        <code> govuk-tag--orange </code>
      </td>
      <td class="govuk-table__cell">
        {{govukTag({
          text: "Declined",
          classes: "govuk-tag--orange"
        })}}
      </td>
    </tr>
    <tr class="govuk-table__row">
      <td class="govuk-table__cell">
        <code> govuk-tag--yellow </code>
      </td>
      <td class="govuk-table__cell">
        {{govukTag({
          text: "Delayed",
          classes: "govuk-tag--yellow"
        })}}
      </td>
    </tr>
  </tbody>
</table>

Research on this component

The Department for Education contributed the coloured tags. They’re being used in:

  • apply for teacher training (used by citizens)
  • manage teacher training applications (used by teacher training providers)

The tag component previously used uppercase bold text for the tags. This was changed as some research has shown that uppercase text can be harder to read, particularly for longer tag text.

The tag component previously used white text on a dark coloured background. Research from multiple teams found that some users perceived these as buttons and tried to click on them. The design was changed to try and avoid this, by using a lighter background colour and darker text.

Help improve this component

To help make sure that this page is useful, relevant and up to date, you can:

Tell us if your service uses this component

Take part in our usage survey (opens in a new tab) to help us improve this component to better meet the needs of the services that use it.

Need help?

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