Content presentation - Tag

When to use a tag

Use the tag component when it's possible for something to have more than 1 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

Tags are just used to indicate a status. Do not add links. Use adjectives rather than verbs for the names of your tags. Using a verb might make a user think that clicking on them will do something.

Showing 1 or 2 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.

Or it can make sense to have 2 statuses. For example, you may find that you need 1 tag for "Active" users and 1 for "Inactive" users.

Open this default tag example in new window
Copy default tag code 
<table class="hs2-table">
  <thead class="hs2-table__head">
    <tr class="hs2-table__row">
      <th class="hs2-table__header" scope="col"> Name of user </th>
      <th class="hs2-table__header" scope="col"> Status </th>
    </tr>
  </thead>
  <tbody class="hs2-table__body">
    <tr class="hs2-table__row">
      <td class="hs2-table__cell">
        User one
      </td>
      <td class="hs2-table__cell">
        <strong class="hs2-tag hs2-tag--grey">
  Inactive
</strong>

      </td>
    </tr>
    <tr class="hs2-table__row">
      <td class="hs2-table__cell">
        User two
      </td>
      <td class="hs2-table__cell">
        <strong class="hs2-tag hs2-tag--grey">
  Inactive
</strong>

      </td>
    </tr>
    <tr class="hs2-table__row">
      <td class="hs2-table__cell">
        User three
      </td>
      <td class="hs2-table__cell">
        <strong class="hs2-tag">
  Active
</strong>

      </td>
    </tr>
    <tr class="hs2-table__row">
      <td class="hs2-table__cell">
        User four
      </td>
      <td class="hs2-table__cell">
        <strong class="hs2-tag">
  Active
</strong>

      </td>
    </tr>
    <tr class="hs2-table__row">
      <td class="hs2-table__cell">
        User five
      </td>
      <td class="hs2-table__cell">
        <strong class="hs2-tag hs2-tag--grey">
  Inactive
</strong>

      </td>
    </tr>
    <tr class="hs2-table__row">
      <td class="hs2-table__cell">
        User six
      </td>
      <td class="hs2-table__cell">
        <strong class="hs2-tag">
  Active
</strong>

      </td>
    </tr>
    <tr class="hs2-table__row">
      <td class="hs2-table__cell">
        User seven
      </td>
      <td class="hs2-table__cell">
        <strong class="hs2-tag hs2-tag--grey">
  Inactive
</strong>

      </td>
    </tr>
  </tbody>
</table>
Close default tag code
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.

Nunjucks arguments for default tag
Name Type Required Description
Name text Type string Required true Description If `html` is set, this is not required. Text to use within the tag component. If `html` is provided, the `text` argument will be ignored.
Name html Type string Required true Description If `text` is set, this is not required. HTML to use within the tag component. If `html` is provided, the `text` argument will be ignored.
Name classes Type string Required false Description Classes to add to the tag.
Name attributes Type object Required false Description HTML attributes (for example data attributes) to add to the tag.
Copy default tag code 
{% from 'tag/macro.njk' import tag %}

<table class="hs2-table">
  <thead class="hs2-table__head">
    <tr class="hs2-table__row">
      <th class="hs2-table__header" scope="col"> Name of user </th>
      <th class="hs2-table__header" scope="col"> Status </th>
    </tr>
  </thead>
  <tbody class="hs2-table__body">
    <tr class="hs2-table__row">
      <td class="hs2-table__cell">
        User one
      </td>
      <td class="hs2-table__cell">
        {{ tag({
          text: "Inactive",
          classes: "hs2-tag--grey"
        })}}
      </td>
    </tr>
    <tr class="hs2-table__row">
      <td class="hs2-table__cell">
        User two
      </td>
      <td class="hs2-table__cell">
        {{ tag({
          text: "Inactive",
          classes: "hs2-tag--grey"
        })}}
      </td>
    </tr>
    <tr class="hs2-table__row">
      <td class="hs2-table__cell">
        User three
      </td>
      <td class="hs2-table__cell">
        {{ tag({
          text: "Active"
        })}}
      </td>
    </tr>
    <tr class="hs2-table__row">
      <td class="hs2-table__cell">
        User four
      </td>
      <td class="hs2-table__cell">
        {{ tag({
          text: "Active"
        })}}
      </td>
    </tr>
    <tr class="hs2-table__row">
      <td class="hs2-table__cell">
        User five
      </td>
      <td class="hs2-table__cell">
        {{ tag({
          text: "Inactive",
          classes: "hs2-tag--grey"
        })}}
      </td>
    </tr>
    <tr class="hs2-table__row">
      <td class="hs2-table__cell">
        User six
      </td>
      <td class="hs2-table__cell">
        {{ tag({
          text: "Active"
        })}}
      </td>
    </tr>
    <tr class="hs2-table__row">
      <td class="hs2-table__cell">
        User seven
      </td>
      <td class="hs2-table__cell">
        {{ tag({
          text: "Inactive",
          classes: "hs2-tag--grey"
        })}}
      </td>
    </tr>
  </tbody>
</table>
Close default tag code

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.

Open this multiple tag example in new window
Copy multiple tag code 
<table class="hs2-table">
  <thead class="hs2-table__head">
    <tr class="hs2-table__row">
      <th class="hs2-table__header" scope="col"> Application </th>
      <th class="hs2-table__header" scope="col"> Status </th>
    </tr>
  </thead>
  <tbody class="hs2-table__body">
    <tr class="hs2-table__row">
      <td class="hs2-table__cell">
        User one
      </td>
      <td class="hs2-table__cell">
        <strong class="hs2-tag hs2-tag--red">
  Urgent
</strong>

      </td>
    </tr>
    <tr class="hs2-table__row">
      <td class="hs2-table__cell">
        User two
      </td>
      <td class="hs2-table__cell">
        <strong class="hs2-tag hs2-tag--blue">
  New
</strong>

      </td>
    </tr>
    <tr class="hs2-table__row">
      <td class="hs2-table__cell">
        User three
      </td>
      <td class="hs2-table__cell">
        <strong class="hs2-tag hs2-tag--blue">
  New
</strong>

      </td>
    </tr>
    <tr class="hs2-table__row">
      <td class="hs2-table__cell">
        User four
      </td>
      <td class="hs2-table__cell">
        <strong class="hs2-tag hs2-tag--blue">
  New
</strong>

      </td>
    </tr>
    <tr class="hs2-table__row">
      <td class="hs2-table__cell">
        User five
      </td>
      <td class="hs2-table__cell">
        <strong class="hs2-tag hs2-tag--blue">
  New
</strong>

      </td>
    </tr>
    <tr class="hs2-table__row">
      <td class="hs2-table__cell">
        User six
      </td>
      <td class="hs2-table__cell">
        <strong class="hs2-tag hs2-tag--green">
  Finished
</strong>

      </td>
    </tr>
    <tr class="hs2-table__row">
      <td class="hs2-table__cell">
        User seven
      </td>
      <td class="hs2-table__cell">
        <strong class="hs2-tag hs2-tag--yellow">
  Waiting on
</strong>

      </td>
    </tr>
  </tbody>
</table>
Close multiple tag code
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.

Nunjucks arguments for multiple tag
Name Type Required Description
Name text Type string Required true Description If `html` is set, this is not required. Text to use within the tag component. If `html` is provided, the `text` argument will be ignored.
Name html Type string Required true Description If `text` is set, this is not required. HTML to use within the tag component. If `html` is provided, the `text` argument will be ignored.
Name classes Type string Required false Description Classes to add to the tag.
Name attributes Type object Required false Description HTML attributes (for example data attributes) to add to the tag.
Copy multiple tag code 
{% from 'tag/macro.njk' import tag %}

<table class="hs2-table">
  <thead class="hs2-table__head">
    <tr class="hs2-table__row">
      <th class="hs2-table__header" scope="col"> Application </th>
      <th class="hs2-table__header" scope="col"> Status </th>
    </tr>
  </thead>
  <tbody class="hs2-table__body">
    <tr class="hs2-table__row">
      <td class="hs2-table__cell">
        User one
      </td>
      <td class="hs2-table__cell">
        {{ tag({
          text: "Urgent",
          classes: "hs2-tag--red"
        })}}
      </td>
    </tr>
    <tr class="hs2-table__row">
      <td class="hs2-table__cell">
       User two
      </td>
      <td class="hs2-table__cell">
        {{ tag({
          text: "New",
          classes: "hs2-tag--blue"
        })}}
      </td>
    </tr>
    <tr class="hs2-table__row">
      <td class="hs2-table__cell">
        User three
      </td>
      <td class="hs2-table__cell">
        {{ tag({
          text: "New",
          classes: "hs2-tag--blue"
        })}}
      </td>
    </tr>
    <tr class="hs2-table__row">
      <td class="hs2-table__cell">
        User four
      </td>
      <td class="hs2-table__cell">
        {{ tag({
          text: "New",
          classes: "hs2-tag--blue"
        })}}
      </td>
    </tr>
    <tr class="hs2-table__row">
      <td class="hs2-table__cell">
        User five
      </td>
      <td class="hs2-table__cell">
        {{ tag({
          text: "New",
          classes: "hs2-tag--blue"
        })}}
      </td>
    </tr>
    <tr class="hs2-table__row">
      <td class="hs2-table__cell">
        User six
      </td>
      <td class="hs2-table__cell">
        {{ tag({
          text: "Finished",
          classes: "hs2-tag--green"
        })}}
      </td>
    </tr>
    <tr class="hs2-table__row">
      <td class="hs2-table__cell">
        User seven
      </td>
      <td class="hs2-table__cell">
        {{ tag({
          text: "Waiting on",
          classes: "hs2-tag--yellow"
        })}}
      </td>
    </tr>
  </tbody>
</table>
Close multiple tag code

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 makes sense to use hs2-tag--red for a tag that reads "Urgent".

Because tags with solid colours tend to stand out more, it's usually best to avoid mixing solid colours and tints: use one or the other. This matters less if you're only using 2 colours. For example, it's okay to use the tint hs2-tag--grey and solid blue tags together if you only need 2 statuses.

We use a border of the same colour as the tag text to stand out against the HS2 page background colour.

Additional colours

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

Open this colours tag example in new window
Copy colours tag code 
<table class="hs2-table">
  <thead class="hs2-table__head">
    <tr class="hs2-table__row">
      <th class="hs2-table__header" scope="col"> Class name </th>
      <th class="hs2-table__header" scope="col"> Tag </th>
    </tr>
  </thead>
  <tbody class="hs2-table__body">
    <tr class="hs2-table__row">
      <td class="hs2-table__cell">
        <code> hs2-tag--white </code>
      </td>
      <td class="hs2-table__cell">
        <strong class="hs2-tag hs2-tag--white">
  Started
</strong>

      </td>
    </tr>
    <tr class="hs2-table__row">
      <td class="hs2-table__cell">
        <code> hs2-tag--grey </code>
      </td>
      <td class="hs2-table__cell">
        <strong class="hs2-tag hs2-tag--grey">
  Not started
</strong>

      </td>
    </tr>
    <tr class="hs2-table__row">
      <td class="hs2-table__cell">
        <code> hs2-tag--green </code>
      </td>
      <td class="hs2-table__cell">
        <strong class="hs2-tag hs2-tag--green">
  New
</strong>

      </td>
    </tr>
    <tr class="hs2-table__row">
      <td class="hs2-table__cell">
        <code> hs2-tag--aqua-green </code>
      </td>
      <td class="hs2-table__cell">
        <strong class="hs2-tag hs2-tag--aqua-green">
  Active
</strong>

      </td>
    </tr>
    <tr class="hs2-table__row">
      <td class="hs2-table__cell">
        <code> hs2-tag--blue </code>
      </td>
      <td class="hs2-table__cell">
        <strong class="hs2-tag hs2-tag--blue">
  Pending
</strong>

      </td>
    </tr>
    <tr class="hs2-table__row">
      <td class="hs2-table__cell">
        <code> hs2-tag--purple </code>
      </td>
      <td class="hs2-table__cell">
        <strong class="hs2-tag hs2-tag--purple">
  Received
</strong>

      </td>
    </tr>
    <tr class="hs2-table__row">
      <td class="hs2-table__cell">
        <code> hs2-tag--pink </code>
      </td>
      <td class="hs2-table__cell">
        <strong class="hs2-tag hs2-tag--pink">
  Sent
</strong>

      </td>
    </tr>
    <tr class="hs2-table__row">
      <td class="hs2-table__cell">
        <code> hs2-tag--red </code>
      </td>
      <td class="hs2-table__cell">
        <strong class="hs2-tag hs2-tag--red">
  Rejected
</strong>

      </td>
    </tr>
    <tr class="hs2-table__row">
      <td class="hs2-table__cell">
        <code> hs2-tag--orange </code>
      </td>
      <td class="hs2-table__cell">
        <strong class="hs2-tag hs2-tag--orange">
  Declined
</strong>

      </td>
    </tr>
    <tr class="hs2-table__row">
      <td class="hs2-table__cell">
        <code> hs2-tag--yellow </code>
      </td>
      <td class="hs2-table__cell">
        <strong class="hs2-tag hs2-tag--yellow">
  Delayed
</strong>

      </td>
    </tr>
  </tbody>
</table>
Close colours tag code
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.

Nunjucks arguments for colours tag
Name Type Required Description
Name text Type string Required true Description If `html` is set, this is not required. Text to use within the tag component. If `html` is provided, the `text` argument will be ignored.
Name html Type string Required true Description If `text` is set, this is not required. HTML to use within the tag component. If `html` is provided, the `text` argument will be ignored.
Name classes Type string Required false Description Classes to add to the tag.
Name attributes Type object Required false Description HTML attributes (for example data attributes) to add to the tag.
Copy colours tag code 
{% from 'tag/macro.njk' import tag %}

<table class="hs2-table">
  <thead class="hs2-table__head">
    <tr class="hs2-table__row">
      <th class="hs2-table__header" scope="col"> Class name </th>
      <th class="hs2-table__header" scope="col"> Tag </th>
    </tr>
  </thead>
  <tbody class="hs2-table__body">
    <tr class="hs2-table__row">
      <td class="hs2-table__cell">
        <code> hs2-tag--white </code>
      </td>
      <td class="hs2-table__cell">
        {{ tag({
          text: "Started",
          classes: "hs2-tag--white"
        })}}
      </td>
    </tr>
    <tr class="hs2-table__row">
      <td class="hs2-table__cell">
        <code> hs2-tag--grey </code>
      </td>
      <td class="hs2-table__cell">
        {{ tag({
          text: "Not started",
          classes: "hs2-tag--grey"
        })}}
      </td>
    </tr>
    <tr class="hs2-table__row">
      <td class="hs2-table__cell">
        <code> hs2-tag--green </code>
      </td>
      <td class="hs2-table__cell">
        {{ tag({
          text: "New",
          classes: "hs2-tag--green"
        })}}
      </td>
    </tr>
    <tr class="hs2-table__row">
      <td class="hs2-table__cell">
        <code> hs2-tag--aqua-green </code>
      </td>
      <td class="hs2-table__cell">
        {{ tag({
          text: "Active",
          classes: "hs2-tag--aqua-green"
        })}}
      </td>
    </tr>
    <tr class="hs2-table__row">
      <td class="hs2-table__cell">
        <code> hs2-tag--blue </code>
      </td>
      <td class="hs2-table__cell">
        {{ tag({
          text: "Pending",
          classes: "hs2-tag--blue"
        })}}
      </td>
    </tr>
    <tr class="hs2-table__row">
      <td class="hs2-table__cell">
        <code> hs2-tag--purple </code>
      </td>
      <td class="hs2-table__cell">
        {{ tag({
          text: "Received",
          classes: "hs2-tag--purple"
        })}}
      </td>
    </tr>
    <tr class="hs2-table__row">
      <td class="hs2-table__cell">
        <code> hs2-tag--pink </code>
      </td>
      <td class="hs2-table__cell">
        {{ tag({
          text: "Sent",
          classes: "hs2-tag--pink"
        })}}
      </td>
    </tr>
    <tr class="hs2-table__row">
      <td class="hs2-table__cell">
        <code> hs2-tag--red </code>
      </td>
      <td class="hs2-table__cell">
        {{ tag({
          text: "Rejected",
          classes: "hs2-tag--red"
        })}}
      </td>
    </tr>
    <tr class="hs2-table__row">
      <td class="hs2-table__cell">
        <code> hs2-tag--orange </code>
      </td>
      <td class="hs2-table__cell">
        {{ tag({
          text: "Declined",
          classes: "hs2-tag--orange"
        })}}
      </td>
    </tr>
    <tr class="hs2-table__row">
      <td class="hs2-table__cell">
        <code> hs2-tag--yellow </code>
      </td>
      <td class="hs2-table__cell">
        {{ tag({
          text: "Delayed",
          classes: "hs2-tag--yellow"
        })}}
      </td>
    </tr>
  </tbody>
</table>
Close colours tag code

Accessibility

All contrasts between text and background meet level AAA of WCAG 2.0. Read more about accessibility and colour.