Components

Tag - Status

Use with caution: Candidate Web

A status tag indicates the current state or condition of content, processes, or items.

Examples

Status Tags use semantic colors to convey meaning and priority, aligning with the same color conventions used in the Alert component. Each color variation has a specific semantic meaning that should be consistently applied.

Informational status

View va-tag-status informational in Storybook

Used to provide helpful information or something that warrants a user’s attention. Not used for negative consequences.

Warning status

View va-tag-status warning in Storybook

Used to warn a user, such as when there are negative consequences, or when an action cannot continue.

Success status

View va-tag-status success in Storybook

Used to indicate success.

Error status

View va-tag-status error in Storybook

Used to indicate critical issues, failure states, or items that require immediate attention.

Usage

When to use a Status Tag

To communicate current state or progress. Status Tags help users quickly understand the status of an item, process, or workflow—such as “Pending,” “Approved,” or “Error”—at a glance.
To indicate urgency or required action. Use warning or error Status Tags to signal items that need attention or immediate action, helping users prioritize tasks.
To provide scannable feedback at a glance. Status Tags combine color, icons, and short labels to communicate meaning consistently, making it easier to scan lists, tables, or dashboards.

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.

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

When you might confuse tags with buttons. For example, if tags appear near buttons on the page, users may mistake them for interactive elements.
For labels longer than 1-3 words. Tags work best with brief, scannable text. For longer descriptive text, consider using other options like the Status via label with indicator within the Card component.
When the Status Tag functions as a title. Don’t use a Status Tag when the tag content is more accurately described as the title or primary identifier of the content. Instead, use that text as the card’s heading.
Consider the Eyebrow Header style as an alternative. The Eyebrow Header is a short, descriptive title placed above the main heading to provide additional context and maintain consistency.
When lack of change in content makes tags ineffective. If content updates are infrequent users may not notice or expect “new” tags. Use tags to call attention to a change in status.
For system-wide alerts. Use the Alert for page-level or application-level messaging that requires more context or action from you.
For temporary feedback. Consider using the Dismissable Alert for web components and the Snackbar for Mobile app component for brief, dismissible feedback messages.
When you need to mix status tags and tags in a way that confuses their meaning. Always use semantic colors for Status Tags and neutral or brand colors for Tags.
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

Status updates within containers. Use Status Tags to indicate status within containers such as cards, tables, or other UI elements. See the Card guidance when using a Tag within cards.
For data-heavy interfaces. Use Status Tags to help users quickly scan and prioritize information based on semantic meaning.
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.
Test for user confusion. Users might confuse tags with buttons. Always conduct usability testing to make sure your particular implementation is not causing frustration.
Use tags sparingly. Don’t overdo it — if everything on a page is called out as important, nothing is important.
Use semantic colors consistently. Apply the same color meanings across all components (tags, alerts, etc.) to create a cohesive experience for users.
For status within cards. When using tags to communicate status within card components, see the Card component status guidance for specific implementation details and best practices.

Accessibility considerations

Color and meaning. When colored tags are used to convey semantic meaning, ensure that the information is also available through other means such as descriptive text, icons, or contextual clues within the interface. Don’t rely solely on color to communicate important information. Use consistent text patterns and clear language that reinforces the visual meaning.
Contrast requirements. All colored 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. Status 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. The Tag Status component announces hidden screen reader text, “Status” before the content of the tag is announced (for example: “Status, Approved” or “Status, Error”). This helps users understand that this is a status indicator and not a generic label. This additional context improves comprehension since much of the semantic meaning is communicated visually through color. Teams cannot change this announcement pattern at this time.
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 status updates and aria-live="assertive" only for critical status changes that require immediate attention. Avoid announcing rapid or frequent status changes that could overwhelm screen reader users.
Cognitive accessibility. Use consistent placement and behavior of Status Tags across the application to help users with cognitive disabilities predict where to find status information. Keep tag text simple and avoid technical jargon that Veterans may not understand. Don’t overwhelm users with too many status indicators on a single page or interface.

Content considerations

Be concise. Keep tag text brief and scannable. Use 1-3 words when possible.
Use consistent terminology. Apply the same language for similar statuses across the platform (e.g., always use “Approved” rather than mixing “Approved,” “Complete,” and “Done”).
Match semantic meaning. Ensure the tag text aligns with its color meaning. Don’t use error-colored tags for positive messages.
Consider context. The tag’s meaning should be clear within the context where it appears. Avoid jargon or technical terms that Veterans may not understand.

Status examples by semantic color

The following status names are known to be in-use across VA.gov (as of October 2024):

Appeals has over 40 status labels.
Appointments:
- Upcoming (Informational)
- Requested (Informational)
- Past (Informational)
- Canceled (Error)
Claims:
- Claim received (Informational)
- Initial review (Informational)
- Evidence gathering, review, and decision (Informational)
- Preparation for notification (Informational)
- Complete (Success)

Component checklist

Web Platform

42%

3 of 7 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: Conditional

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: 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 - Status component. Your input helps us make the design system better for everyone.

Get immediate support in #platform-design-system for technical or urgent issues.
Explore all feedback channels for additional ways to share your input.

Edit this page in GitHub (Permissions required)

Last updated: Oct 22, 2025