Components

Tag

A tag draws attention to new or categorized content elements.

Default tag

Info

Big tag

Big
<h3 class="site-preview-heading">Default tag</h3>
<span class="usa-tag">Info</span>

<h3 class="site-preview-heading">Big tag</h3>
<span class="usa-tag usa-tag--big">Big</span>

Guidance

When to use the tag component

  • To draw attention to new, important content. Tags can focus attention on important content on that might otherwise be missed.
  • To filter results with one or more tags.
  • To indicate the number of new or unread items within a container. For example, to indicate the number of unread emails within a person’s inbox.

When to consider something else

  • Confusion with buttons. Avoid tags if they might appear in the same area of the page as buttons.
  • New or updated content. To call attention to new or updated content, consider changing the background color of the object itself or experiment with changing the font weight.
  • When users already expect content to be updated frequently. For example, on a site dedicated to breaking news. In this case placing the new content at the top may be enough.

Usability guidance

  • Users frequently confuse tags as buttons. Always conduct usability testing to make sure your particular implementation is not causing frustration.
  • If your tags aren’t interactive, disable hover, focus, and active styles.
  • Don’t mix interactive and static tags. Once you establish a pattern for how tags behave on your site, users will expect that behavior every time.
  • Don’t overdo it. If everything on a page is called out as important, nothing commands unique attention.

Accessibility guidance

  • Use ARIA live regions to highlight dynamically loaded content. When tags are used to call out new content that is dynamically loaded onto a page, be sure to use ARIA live regions to alert screen readers of the change.

Using the tag component

Tag settings

This component has no settings.

Tag variants

Variant Description

.usa-tag--big

A tag with increased padding and font size.

Package

  • Package usage: @forward "usa-tag";
  • Dependencies: uswds-fonts

Latest updates

Meaningful code and guidance updates are listed in the following table:

Date USWDS version Affects Breaking Description
2022-04-28 3.0.0
  • Assets
  • JavaScript
  • Styles
Breaking

Breaking Updated to Sass module syntax and new package structure. More information: uswds#4656