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.


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.



Use: Best practice
Alerts keep users informed of important and sometimes time-sensitive changes.

Examples - Default

Informational alert

View va-alert in Storybook

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

Warning alert

View va-alert in Storybook

Used to warn a user, such as when there are negative consequences, or when something has gone wrong.

Success alert

View va-alert in Storybook

Used to indicate success.

Error alert

View va-alert in Storybook

Used when there is a problem or something destructive is about to occur.

Sign in or tool prompt

View va-alert in Storybook

Used to prompt a user to sign in, create an account, or launch an online tool to access certain information.

Examples - Default variations

Heading level

View va-alert in Storybook

Alerts should contain headings.


View va-alert in Storybook

  • Any alert variation can be dismissible, including background-color only alerts. This example shows an informational alert that can be dismissed.
  • Allow a user to dismiss a notification wherever appropriate.

Dismissible Background Only

View va-alert in Storybook

Dismissible Background Only Icon

View va-alert in Storybook

Examples - Background color only

Background color only alert

Any style of alert box can be modified to be a background-color-only alert. Use background alerts for immediate feedback, such as in single-page applications or Ajax forms. They shouldn’t be used for static alert messaging.

View va-alert in Storybook

  • Some users might not be able to distinguish differences in the background color or see the color at all. Don’t rely on color alone to convey context.
  • Messaging should be direct and concise. Aim for one or two lines.
  • Don’t use headings in background alerts.

Background color only alert with icon

A background alert may be used with an icon to draw attention to important feedback. The iconography for background alerts is consistent with the way icons are used in standard alert boxes.

View va-alert in Storybook


When to use alerts

  • User feedback. Use Alert for feedback messages that respond to an action a user has taken and to draw their attention to something that they need to correct or to confirm successful completion of a task. These messages use success and error variations.
  • In-application system status. An exception to the above is providing information to the user, unprompted, about a problem with a particular application. These system status messages typically use an error or warning variation and do not require user action.
  • Engagement messages that nudge the user to enter or update data. Engagement messages typically use the informational variation and ask the user to take an action.
  • Access messages when a user tries to access an item that is not available to them. Access messages typically warn the user that something they tried to access is not working correctly or is temporarily unavailable. These often use the error or warning variations.

When to consider something else

  • Destructive actions. If an action will result in destroying a user’s work (for example, deleting an application) use a more intrusive pattern, such as a confirmation modal dialogue, to allow the user to confirm that this is what they want.
  • Unprompted and in-page alerts. Consider the Alert - Expandable component to draw attention to important information on the page that is not a response to user feedback.
  • Clarifying background information. Use the Additional info component when clarifying outcomes for an input or a form question as well as providing background information. Keep in mind that Alert - Expandable should warrant an alert and be used sparingly. The value of any type of alert is diminished if the page is littered with alerts of equal weight.
  • System maintenance. Most system messages related to maintenance are handled by the Banner - Maintenance component.

How to use alerts

When the user is required to do something in response to an alert, let them know what they need to do and make that task as easy as possible. Think about how much context to provide with your message. A notification of a system change may require more contextual information than a validation message. The message should be concise, in plain language, and adhere to voice and tone principles.

  • On long forms, always include inline validation in addition to any error messages that appear at the top of the form.
  • Allow a user to dismiss a notification wherever appropriate.
  • Don’t include notifications that aren’t related to the user’s current goal.
  • Don’t stack alerts one after the other.
  • If the alert appears within the page body content, it should be co-located with relevant content.
  • Alerts should not contain other expandable components such as the Additional info component.

Choosing between variations

By default use the standard Alert variation. Use the background-only variation for immediate feedback, such as in single-page applications or dynamic Javascript driven forms.

Code usage

Attributes and Properties

Property Attribute Type Default Description
backgroundOnly background-only boolean false If `true`, renders the alert with only a background color corresponding to the status - no icon or left border.
closeBtnAriaLabel close-btn-aria-label string 'Close notification' Aria-label text for the close button.
closeable closeable boolean false If `true`, a close button will be displayed.
disableAnalytics disable-analytics boolean false If `true`, doesn't fire the CustomEvent which can be used for analytics tracking.
fullWidth full-width boolean false If `true`, the alert will be full width. Should be for emergency communication only.
showIcon show-icon boolean false This option only takes effect when background-only is true. If `true`, the background-only alert will include an icon.
status status string 'info' Determines the icon and border/background color. One of `info`, `error`, `success`, `warning`, or `continue`
visible visible boolean true If `true`, the alert will be visible.


Name Description
closeEvent Fires when the component is closed by clicking on the close icon. This fires only when closeable is true.
component-library-analytics The event used to track usage of the component. This is emitted when an anchor link is clicked and disableAnalytics is not true.
va-component-did-load Fires when the component has successfully finished rendering for the first time.

Content considerations

  • Be polite in error messages — don’t place blame on the user.
  • Users generally won’t read documentation, but they’ll read a message that helps them resolve an error; include some educational material in your error message.
  • But don’t overdo it — too many notifications will either overwhelm or annoy the user and are likely to be ignored.
  • Don’t use jargon and computer code in the message.

View content for messages

Review the help users to recover from errors pattern

Accessibility considerations

  • Use the ARIA role="alert" to inform assistive technologies of a time-sensitive and important message that isn’t interactive. If the message is interactive, use the alertdialog role instead.
  • Don’t visually hide alert messages on the page and then make them visible when they are needed. Users of older assistive technologies may still be able to perceive the alert messages even if they are not currently applicable.
  • Don’t automatically dismiss an alert based on a timer or time limit.
Edit this page in GitHub (Permissions required)
Last updated: Aug 25, 2022