Tag - Status

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.

Neutral status

View va-tag-status neutral in Storybook

Use the neutral status when a state or condition doesn’t fit the informational, warning, success, or error semantic colors, such as an inactive or default state that doesn’t need the user’s attention.

Informational status

View va-tag-status info in Storybook

Use the informational status to provide helpful information or something that warrants a user’s attention. Do not use for negative consequences.

Warning status

View va-tag-status warning in Storybook

Use the warning status 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

Use the success status to indicate success.

Error status

View va-tag-status error in Storybook

Use the error status to indicate critical issues, failure states, or items that require immediate attention.

Big status tag

View va-tag-status big in Storybook

Use the big variant when a single Status Tag needs more visual weight, such as when it applies to an entire page rather than an item within a list or container. See the Size variants section for guidance on choosing between the default and big sizes.

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.
• To communicate time-sensitive status information. Use the informational Status Tag to display relevant dates, such as expiration or deadline dates (e.g., “Expires on MM/DD/YYYY”).

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, error, or neutral
• 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

• 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 shouldn’t be interactive. Tags are designed to be static labels that convey information, not clickable elements. They shouldn’t 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 isn’t 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 Status guidance for specific implementation details and best practices.
• Use sentence case. While Tags without status are capitalized, status tags use sentence case to improve readability in case the status text is longer than 1–2 words.

Size variants

Status Tags and Tags come in 2 sizes: default and big. Both sizes share the same colors, icons, and content guidance. Use the default size in most cases. Use the big variant sparingly, and only when a single tag needs to stand out as the primary label for a page.

When to use the big variant

• When the tag applies to an entire page, such as a single Status Tag placed near a page title to show the overall status of a claim, application, or record.

When to use the default size

• When the tag appears inline with other content, such as within a sentence, list item, or table cell.
• When the tag is used inside a Card or other container, like the Card or Card - status component.
• When multiple tags appear on the same page, since the default size keeps the page from feeling visually heavy when several tags are shown at once.

Code usage

Content considerations

• Be concise. Keep Tag text brief and scannable. Use 1-3 words when possible. Date-based labels (e.g., “Expires on MM/DD/YYYY”) may exceed this but should still be as concise as 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)
• General:
  • Expires on MM/DD/YYYY (Informational)
  • Inactive (Neutral)

Accessibility considerations

• Color and meaning. When Status 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 Status 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.
• Context. Users must be able to easily identify the content that is associated with the Status Tag. The visual design and the HTML structure around the Status Tag should both make this clear. For example, if the Status Tag applies to a heading, wrap the tag inside that heading element.
• Keyboard navigation. Status Tags are static, non-interactive elements that shouldn’t receive keyboard focus, while still being readable as normal page content (including by screen readers). 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 Status Tag component announces hidden screen reader text, “Status” before the content of the tag is announced (for example: “Status, Success” 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 a Status Tag is dynamically added or updated on an already loaded page and the change needs to be announced to screen reader users, use a live region on the tag’s wrapping element. To to this, create a container with role="status" before the change occurs, then add or update the Tag within that container. Do not add role="status" directly to the Tag when it is inserted; screen reader support for newly created, already-populated live regions is inconsistent. Tags that are present when a new page loads do not need role="status" and will be available to screen readers through normal page navigation.
• 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.

Accessibility tests

The Design System team tested this component in isolation across a mix of browsers and assistive technologies using the . Our results may not capture accessibility issues that arise from surrounding context like page structure, content, or how multiple components interact.

To ensure accessibility, you must also test the Tag status component within your own product. See the for what we tested and what you need to test.

Related

• Tag
• Alert
• Card
• Snackbar

Component checklist

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.