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

Card - Status

Don't use: proposed Web
Card Status is a structured card that requires specific information to enforce a consistent pattern for status-driven scenarios.

Examples

Default

View va-card-status default in Storybook

With Label

View va-card-status with label in Storybook

With Error

View va-card-status with error in Storybook

Usage

When to use Card Status

  • Framing a call to action. Card Status highlights and frames a specific call to action or decision a user needs to take.
  • Conveying status. Card Status contains information with a status such as appointments, claims, or missing required information.
  • Giving feedback for data within the card. Card Status allows for an error state that conveys immediate feedback for users to correct their data.

When to consider something else

  • When you need flexible content structure. Use the Card component when you need full control over the card’s content and structure, rather than working with predefined props.
  • When status isn’t the focus. Use the Card component for informational cards where status communication isn’t the primary purpose.
  • When you need multiple calls to action. Use the Card component if you need more than one call-to-action (Card allows up to 3 CTAs).

How this component works

Key difference from Card: While Card is a flexible container where teams build and pass in their own content, Card Status is a structured component with required props that enforce a consistent pattern for status-driven scenarios.

Default

The default Card Status shows a heading, body text, and a link
The default Card Status displays a heading, body text, and action link.

Card Status requires specific props to enforce a consistent pattern:

Required props:

  • heading - The card title
  • body - The descriptive text
  • link-text and link-href - The action link
  • status (optional) - Status tag using Tag - Status

The component automatically handles the layout, accessibility, and visual treatment, ensuring consistency across implementations.

Status display

Card Status shows a status label, a heading, body text, and a link
Card Status with a status label displays the label, heading, body text, and action link.

The status prop uses the Tag - Status component to indicate when information is missing or requires user attention. The component programmatically announces the status to screen readers along with the card header. See accessibility considerations for implementation details.

Error state

Card Status with an error state, showing a status label, a heading, error text, body text, and a link. The card is wrapped in a red border to indicate an error.
Card Status in an error state displays a red border, status label, heading, error message, body text, and action link.

This state is triggered when validation errors occur, such as when a user tries to proceed in a form flow without providing required information. Card Status, in the error state, follows VADS error styling and displays inline error messages that automatically announce to screen readers. The error message clearly states what’s wrong and how to fix it. After the user provides the missing information, the card returns to its default state.

Behavior

Calls to action (CTA)

  • Single CTA only. Card Status supports only one call-to-action, typically to add or edit data. This is more restrictive than the standard Card component, which allows up to 3 CTAs.
  • Use action links. The CTA should use a secondary action link.

Placement

Card Status uses the same placement, dimensions, and layout as described in the Card component.

Code usage

Content considerations

Card Status follows the same content considerations as the Card component.

Additionally:

  • Clear status labels. Use concise, plain language status labels (e.g., “Missing”, “In progress”, “Completed”).
  • Actionable error messages. Error messages must follow the VA.gov pattern: state what’s wrong and how to fix it.

Accessibility considerations

Card Status follows the same basic accessibility considerations as the Card component, including list markup and keyboard navigation.

The Card Status component handles most status and error accessibility automatically and meets WCAG 2.2 AA criteria. Teams need to:

  • Set appropriate heading levels. Choose the heading level that fits your page’s outline structure. For example, if Card Status appears in a section under an <h2>, use <h3> for card headings.
  • Write clear error messages. Follow the VA.gov pattern: state what’s wrong and how to fix it.

How Card Status handles accessibility programmatically

Status announcements:

  • Status uses the Tag - Status component with role="status"
  • Includes visually hidden “Status:” prefix for screen reader context
  • The component programmatically associates status with the card heading

Error handling:

  • Error messages wrapped in role="alert" for automatic announcement
  • Errors linked to action links via aria-describedby
  • Focus remains on the action link (not moved to error) to prevent disorientation
  • Error state visually indicated by icon and text, not color alone

Heading structure:

  • Card headings use semantic heading tags (teams set these based on page structure)
  • Screen readers read status and heading together

Keyboard navigation:

  • Tab key navigates to the action link within the card
  • Enter key or spacebar activates the link

Component checklist

Web Platform

58%

7 of 12 complete

Updated: 01-29-2026

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
2026-01-29
Code review
Pass
Readability
Conditional

Note: This category is dependent on how you use this component. Test this for accessibility in your project.

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

Web

Component depicted in all responsive breakpoints.

Interactive states

Web

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

Tokens

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

Web

Component designed to work in all responsive breakpoints.

Interactive states

Web

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

Tokens

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

Edit this page in GitHub (Permissions required)
Last updated: Feb 03, 2026