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

Use with caution: available Web
Card Status displays information like appointments or contact details with a single action link and optional status. It uses required props to maintain consistency.

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 make.
  • 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).
  • When you need to include a Critical Action component. Use the Card component or Service List Item with a Critical Action component if you need both an urgent action reminder and a secondary action link. Card Status only supports one call to action and cannot include Critical Action.

How this component works

Card Status differs from Card in its structure. While Card is a flexible container where teams build their own content, Card Status uses required props to maintain consistency. It provides a single action link and optional status display for information like appointments, claims, or contact details.

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.
  • Cannot include Critical Action. Because Card Status is limited to one call to action, it cannot include the Critical Action component, which is itself a link. If you need both an urgent action reminder and another action link, use the Card component or Service List Item instead.
  • 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

Web

Attributes and Properties

Property Attribute Type Default Description error error string

The error message to render.

 headerLevel header-level number 3

Header level. Must be between 1 and 6

 headerText header-text string

Text to be displayed in the card header.

 linkHref link-href string

Sets the href for the card link.

 linkText link-text string

Sets the text for the card link.

 required required boolean false

Sets the card to required and renders the (*Required) text.

 subheaderText subheader-text string

Text to be displayed in the card subheader. Heading level will be +1 of headerLevel Prop.

 tagStatus tag-status "error" | "info" 'info'

The status variant of the tag. Determines the background color and icon.

 tagText tag-text string

The text to be displayed in the tag element.

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 have three key responsibilities.

  • 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.
  • Provide descriptive link text. Link text should clearly describe the action. For example, instead of “Edit,” use “Edit mailing address.”

How Card Status handles accessibility programmatically

Status announcements:

  • Status uses the Tag - Status component with role="status". The Tag Status component includes visually hidden text that announces “Status” before the tag text (for example, “Status, Error”), and teams can’t change this announcement pattern.
  • 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 19, 2026