Skip to main content
U.S. flag

An official website of the United States government

Dot gov

The .gov means it’s official.
Federal government websites often end in .gov or .mil. Before sharing sensitive information, make sure you’re on a federal government site.

Https

The site is secure.
The https:// ensures that you are connecting to the official website and that any information you provide is encrypted and transmitted securely.

Components

Tag

Use: Deployed Web
A tag draws attention to new or important content.

Examples

Default tag

View View Tag in Storybook

Used to draw attention to new or important content, categorize information, or indicate counts. Unlike Status Tags, regular Tags use neutral colors and don’t convey semantic meaning through color.

Usage

When to use a tag

  • To draw attention to new, important content on a page that might otherwise be missed.
  • To categorize results with one or more tags by topic, type, or other categorical information.
  • To indicate quantity or count of new or unread items within a container. For example, to indicate the number of unread emails within a person’s inbox.

When to use a Status Tag vs. a Tag

Status Tags

Status Tags show the current status or progress of something, such as “Claim Approved” or “Appointment Pending.” They use semantic colors and concise text to quickly communicate urgency or outcome.

  • Use for status updates: informational, success, warning, or error.
  • Choose when color and text indicate urgency, priority, or required action.

Tags

Tags organize or group items by type or category (like “Benefit Type” or “Document Category”). They help sort information but don’t indicate status.

  • Use for labeling or categorizing items.
  • Choose when color isn’t tied to urgency or meaning.

Special use cases

Internal VA teams building with the Design System have more flexibility in applying color options for Tags and Status Tags than external or VFS teams. However, always ensure color choices meet accessibility requirements. Maintain sufficient color contrast ratios (WCAG 2.2 AA) between the tag background and the page background, and between the text color and the tag background.

When to consider something else

  • For status communication. Use the Tag - Status component when you need to communicate current state, condition, or progress with semantic color meanings.
  • When users are likely to confuse a static tag with a button. For example, when the label appears in the same area of the page as buttons.
  • When the tag functions as a title. When the tag content is more accurately described as the title or primary identifier of the content. Use the Eyebrow header style, which is a short, descriptive title placed above the main heading to provide additional context.
  • When the tag functions as a link. Tags are not intended to be interactive. Use the critical action component if you’re needing to turn the tag into a clickable element.

How to use tags

  • Users frequently confuse tags as buttons. Always conduct usability testing to make sure your particular implementation is not causing frustration.
  • Tags should not be interactive. Tags are designed to be static labels that convey information, not clickable elements. They should not have hover, focus, or active states that suggest interactivity.
  • Don’t overdo it. If everything on a page is called out as important, nothing is important.

Accessibility considerations

  • Contrast requirements. All tag variations meet WCAG 2.2 AA color contrast requirements for both text and background colors, and between the tag background and the page background.
  • Keyboard navigation. Tags are static, non-interactive elements that should not receive keyboard focus. Ensure tags don’t interfere with the natural keyboard navigation flow of the page. Users navigating with the Tab key should move past tags to the next focusable element without interruption.
  • Screen reader support. Regular Tags are announced as their text content without additional context (unlike Status Tags which include “Status” prefix). Ensure tag text is clear and meaningful when heard out of visual context. For count badges or numerical tags, screen readers will announce the number naturally.
  • Dynamic content. When tags are used to indicate new or updated content that is dynamically loaded onto a page, use ARIA live regions to alert screen readers of the change. Use aria-live="polite" for non-urgent updates and aria-live="assertive" only for critical changes that require immediate attention. Avoid announcing rapid or frequent changes that could overwhelm screen reader users.
  • Cognitive accessibility. Use consistent placement and behavior of Tags across the application to help users with cognitive disabilities predict where to find information. Keep tag text simple and avoid technical jargon that Veterans may not understand.

Component checklist

Web Platform

100%

6 of 6 complete

Updated: October 09, 2025

Maturity

Guidance

Web

Examples, usage, code usage, content considerations, and accessibility considerations are all complete.

Research

Web

VFS team conducted research on this component which is linked from this page.

Stability

Web

Component has been in production for more than 3 months with no significant issues found.

Adoption

Web

Multiple teams have adopted this component.

Accessibility

For more information on each category, see Accessibility testing for design system components.

Platform
Web
Last audit date
2025-10-09
Code review
Pass
Readability
Pass
Automated scans
Pass
Use of color
Pass
Text resizing, zoom, and magnification
Pass
Screen readers
Pass
Input and interaction methods
Pass

Code assets

Variations

Web

Storybook includes all variations (style, size, orientation, optional iconography, selection, error state, etc.)

Responsive

N/A Web

Component depicted in all responsive breakpoints.

Interactive states

N/A Web

Includes all interactive states that are applicable (hover, active, focus, keyboard focus, disabled).

Tokens

N/A Web

All design attributes (color, typography, layout, etc.) are available as tokens.

Internationalization

N/A Web

Describes i18n attributes.

Visual assets

Variations

Web

Figma library includes all variations (style, size, orientation, optional iconography, selection, error state, etc.)

Responsive

N/A Web

Component designed to work in all responsive breakpoints.

Interactive states

N/A Web

Includes all interactive states that are applicable (hover, active, focus, keyboard focus, disabled).

Tokens

N/A Web

All design attributes (color, typography, layout, etc.) are available as tokens.

Legend:

  • Complete
  • Incomplete
  • N/A Not applicable

Provide feedback

Share your feedback, report issues, or suggest improvements for the Tag component. Your input helps us make the design system better for everyone.

Edit this page in GitHub (Permissions required)
Last updated: Oct 16, 2025