Action List

Examples

Summary

View va-action-list summary in Storybook

Launcher

View va-action-list launcher in Storybook

Attention

View va-action-list attention in Storybook

Empty state

View va-action-list empty in Storybook

Usage

When to use Action List

• A group of items a Veteran can open or act on. Use an Action List when you have 2 or more items, such as claims, appointments, prescriptions, payments, or tasks a Veteran can start, that share the same anatomy and the same single action.
• Records a Veteran can check on or act on. Use the summary variation for records like claims, appointments, prescriptions, or payments that a Veteran can open for more detail.
• Tasks a Veteran can start. Use the launcher variation for a set of entry points to tasks, tools, or services, such as applying for a benefit or managing direct deposit.
• Items a Veteran needs to respond to. Use the attention variation for items that need a Veteran’s response, usually by a deadline. You may optionally mark items as unread until it is opened.
• No items to show. Use the empty variation to replace a list when there’s nothing to show, so the section can still explain what a Veteran would see there or what they can do next.

When to consider something else

• When an item needs more than a title and a few short lines of supporting text. Use Card instead.
• When an item needs more than one link or any button. Use Card instead. An Action List item has exactly one action.
• When the content is a single, standalone link with no supporting detail. Use Link - Action instead.
• When the items are benefit services with their own status, action, and detail rows. Use Service List Item instead.
• When the content behind a “Show more” toggle would be arbitrary content rather than more list items. Use Accordion instead.

How this component works

Choose a variation on the list. Every item inside it uses that variation. For example, a list can’t mix launcher items with summary items.

What the items are decides the variation. Work down this list and stop at the first match.

For which section of an authenticated page each variation belongs in, refer to Choosing a section on the Authenticated home page template.

• Summary (default). Records a Veteran can check on or act on, such as claims, payments, appointments, or prescriptions. Each item shows a title, a few lines of supporting text, and an optional status tag. The action title link text is the click target.

• Launcher. Tasks a Veteran can start, such as applying for a benefit or managing direct deposit. Adds a leading icon to the summary anatomy. Always a link.

• Attention. Items a Veteran needs to respond to, usually by a deadline. Each item is shown on its own bordered card. The whole card is clickable. Optionally mark an individual item as unread to call out that it hasn’t been seen yet.

• Empty. The zero state for a section with no items. Shows a reassuring message and, optionally, a next step or call to action. Use this only when the section has something specific to say about having no items; otherwise the component supplies a general default automatically.

Only the attention and summary variations can collapse a long list behind a “Show more” toggle. Use “Show more” when the full set belongs on this page. When the full set lives on another page, show only the first few items and link to that page instead of setting a visible limit. Launcher lists always show every item.

On summary and launcher items, the title link is the click target. On an attention item, the whole card is the target.

Nothing truncates. Titles and supporting text wrap to as many lines as they need. At 200% and 400% zoom and down to a 320px viewport, items stack to a single column and a status tag moves off the trailing edge to a line of its own between the title and the supporting text.

Action List has no loading or error state. While a list’s items are loading, use the Loading indicator in the list’s place. If the items can’t load, use a slim Alert instead. Never show a list that failed to load as an empty state, because that tells a Veteran they have nothing when we don’t actually know.

Anatomy or layout details

• Heading (optional). A short label naming what the list holds, such as “Appointments” or “Needs attention.” Don’t repeat a heading the page already displays above the list.
• Title (required). The item’s name. On summary, launcher, and attention items, the title is the link, so write it to make sense read on its own, like “Compensation and Pension” or “Health chat.”
• Supporting text. Up to 3 short lines below the title, such as a date or a brief description. No links, buttons, or other interactive content belong here, except on an empty item’s call to action.
• Status tag (summary and attention only). Use Tag - Status to show the item’s state, such as “In progress” or “Needs review.” It sits at the item’s trailing edge once the item is wide enough, and it’s the only thing that does. A tag renders with a status icon, so don’t put an action label such as “Download” or “Continue” in it—the label reads as a state the item is in. Carry action labels in the title or the supporting text instead.
• Leading icon (launcher and empty only). On a launcher item, the icon sits in a tinted tile and helps distinguish the entry point. On an empty item, a muted icon can reflect the section’s subject, such as a folder icon for claims.
• Unread indicator (attention only, optional). Items are read by default, so mark an item unread when the Veteran hasn’t seen it yet. It adds the unread styling and an “Unread” announcement for screen readers. Set this only on lists that track whether a Veteran has seen an item. Leave it off for lists that don’t track that state.
• “Show more” toggle (attention and summary variants only, optional). Appears automatically once an attention list or summary list holds more items than the visible limit you set, and selecting it reveals all of the remaining items at once. Don’t set a limit on launcher lists—it has no effect there.

Placement

Place an Action List anywhere a page groups 2 or more related items, such as a dashboard section or a benefits summary page. Use only one variation per list. If a page needs to show both, for example, records to check on and items that need a response, use 2 separate Action Lists, each with its own heading.

Code usage

Content considerations

• Titles that stand alone. Write each item’s title so it makes sense on its own—it’s read aloud as a link name, separate from the rest of the item’s content.
• Launcher titles. For launcher items, write the title as the tool or service name itself, such as “Health chat” or “Upload a form.”
• Short titles and tags. Keep titles short enough to read at a glance, and keep status tags to 1 or 2 words.
• Short headings. Keep a heading to a short noun phrase that names what the list holds, such as “Appointments” or “Needs attention.” Skip the heading if the page already has one above the list.
• Specific empty states. Write an empty state’s message to say something specific: what a Veteran would see here once there’s content, or what they can do next. If you don’t author one, the component shows a general default message.
• One action per item. Don’t place a link or button inside a summary, launcher, or attention item’s supporting text—each item has exactly one action, its title. An empty item is the only variation where you add your own link as its call to action.
• External links and new tabs. When an item’s title leaves VA.gov, display the name of the service where the link is going. If the link should open in a new tab use the “external” prop and refer to Link for when to open a new tab.

Accessibility considerations

• List semantics. Action List items render as a list, so assistive technology announces how many items it contains.
• Accessible names. Each interactive item’s whole accessible name is its visible title, so write titles that make sense read alone, out of context.
• One target per attention card. On attention items, the entire card is the click target, so don’t add a second link or button inside it—it would be visually present but unreachable by pointer.
• Unread indicator. Set the unread indicator only on lists that track read state for a person. It adds a screen-reader announcement and a visual cue; leaving it unset means the item says nothing about having been seen.
• Not color alone. Don’t rely on color alone to communicate the unread state—a bold title and a screen-reader announcement carry that meaning as well.
• Focus on “Show more.” When a user expands or collapses the “Show more” toggle, keyboard focus stays on the toggle so the person doesn’t lose their place.
• New tab warnings. When a link opens in a new tab, use the external prop. This appends “(opens in a new tab)” into the title text and doesn’t rely on the icon to convey meaning. All users will now understand that the link opens in a new window and they don’t have to rely on understanding the icon.

Related

• Card
• Card - Status
• Service List Item
• Link - Action
• Accordion
• Tag - Status
• Category pages — a template built with this component

Component checklist

Provide feedback

Share your feedback, report issues, or suggest improvements for the Action List 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.