<p>
Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.
</p>
<p>
Some options are required for the macro to work; these are marked as "Required" in the option description.
</p>
<p>
If you're using Nunjucks macros in production with "html" options, or ones ending with "html", you must sanitise the HTML to protect against <a href="https://developer.mozilla.org/en-US/docs/Glossary/Cross-site_scripting">cross-site scripting exploits</a>.
</p>
<table class="govuk-table app-options__table" id="options-tag-example--primary">
<caption class="govuk-table__caption govuk-heading-m govuk-visually-hidden">Primary options</caption>
<thead class="govuk-table__head">
<tr class="govuk-table__row">
<th class="govuk-table__header app-options__limit-table-cell" scope="col">Name</th>
<th class="govuk-table__header app-options__limit-table-cell" scope="col">Type</th>
<th class="govuk-table__header" scope="col">Description</th>
</tr>
</thead>
<tbody class="govuk-table__body">
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">text</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
<strong>Required.</strong>
If <code>html</code> is set, this is not required. Text to use within the tag component. If <code>html</code> is provided, the <code>text</code> option will be ignored.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">html</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
<strong>Required.</strong>
If <code>text</code> is set, this is not required. HTML to use within the tag component. If <code>html</code> is provided, the <code>text</code> option will be ignored.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">classes</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
Classes to add to the tag.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">attributes</th>
<td class="govuk-table__cell ">object</td>
<td class="govuk-table__cell ">
HTML attributes (for example data attributes) to add to the tag.
</td>
</tr>
</tbody>
</table>
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 just used to indicate a status, so 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 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 task list 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.
<theadclass="govuk-table__head"><trclass="govuk-table__row"><thclass="govuk-table__header"scope="col"> Name of user </th><thclass="govuk-table__header"scope="col"> Status </th></tr></thead><tbodyclass="govuk-table__body"><trclass="govuk-table__row"><tdclass="govuk-table__cell">
Rachel Silver
</td><tdclass="govuk-table__cell"><strongclass="govuk-tag govuk-tag--grey">
Inactive
</strong></td></tr><trclass="govuk-table__row"><tdclass="govuk-table__cell">
Jesse Smith
</td><tdclass="govuk-table__cell"><strongclass="govuk-tag govuk-tag--grey">
Inactive
</strong></td></tr><trclass="govuk-table__row"><tdclass="govuk-table__cell">
Joshua Wessel
</td><tdclass="govuk-table__cell"><strongclass="govuk-tag">
Active
</strong></td></tr><trclass="govuk-table__row"><tdclass="govuk-table__cell">
Rachael Pepper
</td><tdclass="govuk-table__cell"><strongclass="govuk-tag">
Active
</strong></td></tr><trclass="govuk-table__row"><tdclass="govuk-table__cell">
Stuart Say
</td><tdclass="govuk-table__cell"><strongclass="govuk-tag govuk-tag--grey">
Inactive
</strong></td></tr><trclass="govuk-table__row"><tdclass="govuk-table__cell">
Laura Frith
</td><tdclass="govuk-table__cell"><strongclass="govuk-tag">
Active
</strong></td></tr><trclass="govuk-table__row"><tdclass="govuk-table__cell">
Tim Harvey
</td><tdclass="govuk-table__cell"><strongclass="govuk-tag govuk-tag--grey">
Inactive
</strong></td></tr></tbody></table>
<p>
Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.
</p>
<p>
Some options are required for the macro to work; these are marked as "Required" in the option description.
</p>
<p>
If you're using Nunjucks macros in production with "html" options, or ones ending with "html", you must sanitise the HTML to protect against <a href="https://developer.mozilla.org/en-US/docs/Glossary/Cross-site_scripting">cross-site scripting exploits</a>.
</p>
<table class="govuk-table app-options__table" id="options-multiple-tags-example--primary">
<caption class="govuk-table__caption govuk-heading-m govuk-visually-hidden">Primary options</caption>
<thead class="govuk-table__head">
<tr class="govuk-table__row">
<th class="govuk-table__header app-options__limit-table-cell" scope="col">Name</th>
<th class="govuk-table__header app-options__limit-table-cell" scope="col">Type</th>
<th class="govuk-table__header" scope="col">Description</th>
</tr>
</thead>
<tbody class="govuk-table__body">
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">text</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
<strong>Required.</strong>
If <code>html</code> is set, this is not required. Text to use within the tag component. If <code>html</code> is provided, the <code>text</code> option will be ignored.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">html</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
<strong>Required.</strong>
If <code>text</code> is set, this is not required. HTML to use within the tag component. If <code>html</code> is provided, the <code>text</code> option will be ignored.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">classes</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
Classes to add to the tag.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">attributes</th>
<td class="govuk-table__cell ">object</td>
<td class="govuk-table__cell ">
HTML attributes (for example data attributes) to add to the tag.
</td>
</tr>
</tbody>
</table>
<table class="govuk-table">
<theadclass="govuk-table__head"><trclass="govuk-table__row"><thclass="govuk-table__header"scope="col"> Name of user </th><thclass="govuk-table__header"scope="col"> Status </th></tr></thead><tbodyclass="govuk-table__body"><trclass="govuk-table__row"><tdclass="govuk-table__cell">
Rachel Silver
</td><tdclass="govuk-table__cell">
{{govukTag({
text: "Inactive",
classes: "govuk-tag--grey"
})}}
</td></tr><trclass="govuk-table__row"><tdclass="govuk-table__cell">
Jesse Smith
</td><tdclass="govuk-table__cell">
{{govukTag({
text: "Inactive",
classes: "govuk-tag--grey"
})}}
</td></tr><trclass="govuk-table__row"><tdclass="govuk-table__cell">
Joshua Wessel
</td><tdclass="govuk-table__cell">
{{govukTag({
text: "Active"
})}}
</td></tr><trclass="govuk-table__row"><tdclass="govuk-table__cell">
Rachael Pepper
</td><tdclass="govuk-table__cell">
{{govukTag({
text: "Active"
})}}
</td></tr><trclass="govuk-table__row"><tdclass="govuk-table__cell">
Stuart Say
</td><tdclass="govuk-table__cell">
{{govukTag({
text: "Inactive",
classes: "govuk-tag--grey"
})}}
</td></tr><trclass="govuk-table__row"><tdclass="govuk-table__cell">
Laura Frith
</td><tdclass="govuk-table__cell">
{{govukTag({
text: "Active"
})}}
</td></tr><trclass="govuk-table__row"><tdclass="govuk-table__cell">
Tim Harvey
</td><tdclass="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.
<theadclass="govuk-table__head"><trclass="govuk-table__row"><thclass="govuk-table__header"scope="col"> Application </th><thclass="govuk-table__header"scope="col"> Status </th></tr></thead><tbodyclass="govuk-table__body"><trclass="govuk-table__row"><tdclass="govuk-table__cell">
Joshua Wessel
</td><tdclass="govuk-table__cell"><strongclass="govuk-tag govuk-tag--red">
Urgent
</strong></td></tr><trclass="govuk-table__row"><tdclass="govuk-table__cell">
Rachel Silver
</td><tdclass="govuk-table__cell"><strongclass="govuk-tag govuk-tag--blue">
New
</strong></td></tr><trclass="govuk-table__row"><tdclass="govuk-table__cell">
Laura Frith
</td><tdclass="govuk-table__cell"><strongclass="govuk-tag govuk-tag--blue">
New
</strong></td></tr><trclass="govuk-table__row"><tdclass="govuk-table__cell">
Paul French
</td><tdclass="govuk-table__cell"><strongclass="govuk-tag govuk-tag--blue">
New
</strong></td></tr><trclass="govuk-table__row"><tdclass="govuk-table__cell">
Jesse Smith
</td><tdclass="govuk-table__cell"><strongclass="govuk-tag govuk-tag--blue">
New
</strong></td></tr><trclass="govuk-table__row"><tdclass="govuk-table__cell">
Rachael Pepper
</td><tdclass="govuk-table__cell"><strongclass="govuk-tag govuk-tag--green">
Finished
</strong></td></tr><trclass="govuk-table__row"><tdclass="govuk-table__cell">
Emma Tennant
</td><tdclass="govuk-table__cell"><strongclass="govuk-tag govuk-tag--yellow">
Waiting on
</strong></td></tr></tbody></table>
<p>
Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.
</p>
<p>
Some options are required for the macro to work; these are marked as "Required" in the option description.
</p>
<p>
If you're using Nunjucks macros in production with "html" options, or ones ending with "html", you must sanitise the HTML to protect against <a href="https://developer.mozilla.org/en-US/docs/Glossary/Cross-site_scripting">cross-site scripting exploits</a>.
</p>
<table class="govuk-table app-options__table" id="options-coloured-tags-example--primary">
<caption class="govuk-table__caption govuk-heading-m govuk-visually-hidden">Primary options</caption>
<thead class="govuk-table__head">
<tr class="govuk-table__row">
<th class="govuk-table__header app-options__limit-table-cell" scope="col">Name</th>
<th class="govuk-table__header app-options__limit-table-cell" scope="col">Type</th>
<th class="govuk-table__header" scope="col">Description</th>
</tr>
</thead>
<tbody class="govuk-table__body">
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">text</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
<strong>Required.</strong>
If <code>html</code> is set, this is not required. Text to use within the tag component. If <code>html</code> is provided, the <code>text</code> option will be ignored.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">html</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
<strong>Required.</strong>
If <code>text</code> is set, this is not required. HTML to use within the tag component. If <code>html</code> is provided, the <code>text</code> option will be ignored.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">classes</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
Classes to add to the tag.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">attributes</th>
<td class="govuk-table__cell ">object</td>
<td class="govuk-table__cell ">
HTML attributes (for example data attributes) to add to the tag.
</td>
</tr>
</tbody>
</table>
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’.
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 two colours. For example, it's okay to use the tint govuk-tag--grey and solid blue tags together if you only need two statuses.
Additional colours
If you need more tag colours, you can use the following tints.
<div class="app-example app-example--tabs">
<div class="app-example__toolbar">
<a href="/components/tag/all-colours/index.html" class="app-example__new-window" target="_blank">
Open this
<span class="govuk-visually-hidden">all tag colours</span>
example in a new tab
</a>
</div>
<iframe title="All tag colours example" data-module="app-example-frame" class="app-example__frame app-example__frame--resizable" src="/components/tag/all-colours/index.html" frameBorder="0" loading="lazy"></iframe>
</div>
<span id="options-all-tag-colours-example"></span>
<ul class="app-tabs" role="tablist">
<li class="app-tabs__item js-tabs__item" role="presentation"><a href="#all-tag-colours-example-html" role="tab" aria-controls="all-tag-colours-example-html" data-track="tab-html">HTML</a></li>
<li class="app-tabs__item js-tabs__item" role="presentation"><a href="#all-tag-colours-example-nunjucks" role="tab" aria-controls="all-tag-colours-example-nunjucks" data-track="tab-nunjucks">Nunjucks</a></li>
</ul>
<div class="app-tabs__heading js-tabs__heading"><a href="#all-tag-colours-example-html" aria-controls="all-tag-colours-example-html" data-track="tab-html">HTML</a></div>
<div class="app-tabs__container js-tabs__container" id="all-tag-colours-example-html" role="tabpanel">
<div class="app-example__code">
<pre data-module="app-copy" tabindex="0"><code class="hljs html"><span class="hljs-tag"><<span class="hljs-name">table</span> <span class="hljs-attr">class</span>=<span class="hljs-string">"govuk-table"</span>></span>
<theadclass="govuk-table__head"><trclass="govuk-table__row"><thclass="govuk-table__header"scope="col"> Class name </th><thclass="govuk-table__header"scope="col"> Tag </th></tr></thead><tbodyclass="govuk-table__body"><trclass="govuk-table__row"><tdclass="govuk-table__cell"><code> govuk-tag--grey </code></td><tdclass="govuk-table__cell"><strongclass="govuk-tag govuk-tag--grey">
Inactive
</strong></td></tr><trclass="govuk-table__row"><tdclass="govuk-table__cell"><code> govuk-tag--green </code></td><tdclass="govuk-table__cell"><strongclass="govuk-tag govuk-tag--green">
New
</strong></td></tr><trclass="govuk-table__row"><tdclass="govuk-table__cell"><code> govuk-tag--turquoise </code></td><tdclass="govuk-table__cell"><strongclass="govuk-tag govuk-tag--turquoise">
Active
</strong></td></tr><trclass="govuk-table__row"><tdclass="govuk-table__cell"><code> govuk-tag--blue </code></td><tdclass="govuk-table__cell"><strongclass="govuk-tag govuk-tag--blue">
Pending
</strong></td></tr><trclass="govuk-table__row"><tdclass="govuk-table__cell"><code> govuk-tag--purple </code></td><tdclass="govuk-table__cell"><strongclass="govuk-tag govuk-tag--purple">
Received
</strong></td></tr><trclass="govuk-table__row"><tdclass="govuk-table__cell"><code> govuk-tag--pink </code></td><tdclass="govuk-table__cell"><strongclass="govuk-tag govuk-tag--pink">
Sent
</strong></td></tr><trclass="govuk-table__row"><tdclass="govuk-table__cell"><code> govuk-tag--red </code></td><tdclass="govuk-table__cell"><strongclass="govuk-tag govuk-tag--red">
Rejected
</strong></td></tr><trclass="govuk-table__row"><tdclass="govuk-table__cell"><code> govuk-tag--orange </code></td><tdclass="govuk-table__cell"><strongclass="govuk-tag govuk-tag--orange">
Declined
</strong></td></tr><trclass="govuk-table__row"><tdclass="govuk-table__cell"><code> govuk-tag--yellow </code></td><tdclass="govuk-table__cell"><strongclass="govuk-tag govuk-tag--yellow">
Delayed
</strong></td></tr></tbody></table>
<p>
Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.
</p>
<p>
Some options are required for the macro to work; these are marked as "Required" in the option description.
</p>
<p>
If you're using Nunjucks macros in production with "html" options, or ones ending with "html", you must sanitise the HTML to protect against <a href="https://developer.mozilla.org/en-US/docs/Glossary/Cross-site_scripting">cross-site scripting exploits</a>.
</p>
<table class="govuk-table app-options__table" id="options-all-tag-colours-example--primary">
<caption class="govuk-table__caption govuk-heading-m govuk-visually-hidden">Primary options</caption>
<thead class="govuk-table__head">
<tr class="govuk-table__row">
<th class="govuk-table__header app-options__limit-table-cell" scope="col">Name</th>
<th class="govuk-table__header app-options__limit-table-cell" scope="col">Type</th>
<th class="govuk-table__header" scope="col">Description</th>
</tr>
</thead>
<tbody class="govuk-table__body">
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">text</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
<strong>Required.</strong>
If <code>html</code> is set, this is not required. Text to use within the tag component. If <code>html</code> is provided, the <code>text</code> option will be ignored.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">html</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
<strong>Required.</strong>
If <code>text</code> is set, this is not required. HTML to use within the tag component. If <code>html</code> is provided, the <code>text</code> option will be ignored.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">classes</th>
<td class="govuk-table__cell ">string</td>
<td class="govuk-table__cell ">
Classes to add to the tag.
</td>
</tr>
<tr class="govuk-table__row">
<th class="govuk-table__header" scope="row">attributes</th>
<td class="govuk-table__cell ">object</td>
<td class="govuk-table__cell ">
HTML attributes (for example data attributes) to add to the tag.
</td>
</tr>
</tbody>
</table>