Components

Tag

A tag draws attention to new or categorized content elements.

Passed WCAG 2.1 AA

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

Test the tag component in your own project.

USWDS tested the tag component for accessibility. You should test your implementation, too.

Use tag accessibility tests
  • 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.

Accessibility test status

The USWDS team did 4 tests based on WCAG 2.1 AA success criteria.

Overview of recent accessibility test results:
Total tests
Passed
Passed with exceptions
Conditional
Failed
4 4 0 0 0

Overview of recent accessibility test results:

  • Passed: 4
  • Passed with exceptions: 0
  • Conditional: 0
  • Failed: 0

Learn more on the tag accessibility tests page.

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
2024-05-15 N/A
  • Guidance
 No

Added WCAG compliance tag and accessibility test status section. More information: uswds-site#2645

2022-04-28 3.0.0
  • Assets
  • JavaScript
  • Styles
 Breaking

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