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

Alert

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.

Dismissible

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 should not 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

Usage

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 VA.gov 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.

Placement

Default alerts

  • In most cases, the Default alert (in all of its variations) should be placed directly below the intro text, near the top of the page.
  • When a Default alert is applicable to a specific section of content on a page, it should be placed directly below the header of that section.

Background color only alerts

  • Background alerts related to a form field or section should be placed below the label, legend, or section header.
  • The info variation of the Background alert can be placed between sections.
  • Save-in-progress success and error Background alerts should be placed directly below the Back/Continue button pair. This placement allows for the page content to remain fixed in the same position when the alert updates dynamically.

Choosing between variations

  • Use the Default alert variation in most use cases and within static content pages. Background alerts are not available in Drupal.
  • Use the Background alert variation for immediate feedback within forms and applications. Background alerts are most often displayed immediately after the user has taken an action, and can also be used for save-in-progress success and error messaging.

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.

Events

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

  • 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.

Assign an appropriate ARIA role

In some situations, an ARIA role may need to be added to the alert component for it to work best for people who use assistive technology. ARIA should be used sparingly to supplement and enhance the native features of HTML.

  • Static alert: No role. If the alert is a static alert that exists on the page when the page gets loaded, it likely doesn’t need a role.
  • Timely information that requires action: Use role="alert". If the alert conveys timely or time-sensitive and important information that needs to be acted on before moving forward, use role="alert".
  • Interactive elements: Use role="alertdialog". If the information in the alert contains interactive elements, like links or buttons, use the role="alertdialog" role instead of role="alert".
  • Important but not timely: Use role="region". If the information isn’t timely and doesn’t need to be acted on immediately, but still contains important information that represents a substantial topic on the page, role=”region” may be appropriate. Some roles, like role="region", help assistive technology identify the content as being grouped and separated from the rest of the page content. For example, some assistive technologies can navigate by landmark roles like role="region".

More on ARIA specific roles.

Alternative (alt) text for icons and images

For accessibility best practices, we differentiate between images that are decorative and images that are informative.

  • Decorative images: Dividers or design items that do not provide additional context or content. They may exist on the page for purely aesthetic reasons. They don’t add to the information a user needs and they make little sense, or are unnecessary, when read with a screen reader.
  • Informative images: convey some kind of information. To determine whether an image is informative or not, try removing it from the design. If information is missing with the image removed it means that the image is informative and needs alt text.

Consider the purpose of your graphic and whether alt text will provide any information, benefit, or feeling (e.g. the icons used in this Alert component) If the image will not provide information, benefit, or sentiment then do not provide alt text on the image. For more information on why we must provide relevant and meaningful alt text and how to create quality alt text please refer to the content style guide on Alternative text for images.

Component checklist

Maturity

Guidance
Examples, usage, code usage, content considerations, and accessibility considerations are all complete.
Research
VFS team conducted research on this component which is linked from this page.
Stability
Component has been in production for more than 3 months with no significant issues found.
Adoption
Multiple teams have adopted this component.

Accessibility

Accessible use of color
Color is not used as the only visual means of conveying information (WCAG 2.0 1.4.1).
Accessible contrast
Text has a contrast ratio of at least 4.5:1 for small text and at least 3:1 for large text (WCAG 2.0 1.4.3). Visual information required to identify components and states (except inactive components) has a contrast ratio of at least 3:1 (WCAG 2.1 1.4.11).
Keyboard interactions
Follows WCAG 2.0 standards for keyboard accessibility guidelines and includes a description of the keyboard interactions. All interactive elements can be selected and activated using the keyboard.
Content zoom tested
Component has been tested with the display set to 400% at 1280px viewport width to ensure that the component does not have overlapping text or elements and all interactive elements still operate.
Tested in screen readers
Tested with screen readers to ensure there are no issues with reading order, spelling, dynamic content, and interactive elements.

Code assets

Variations
Storybook includes all variations (style, size, orientation, optional iconography, selection, error state, etc.)
Responsive
Component depicted in all responsive breakpoints.
Interactive states
Includes all interactive states that are applicable (hover, active, focus, keyboard focus, disabled).
Tokens
All design attributes (color, typography, layout, etc.) are available as tokens.
Internationalization
Describes i18n attributes.

Visual assets

Variations
Sketch library includes all variations (style, size, orientation, optional iconography, selection, error state, etc.)
Responsive
Component designed to work in all responsive breakpoints.
Interactive states
Includes all interactive states that are applicable (hover, active, focus, keyboard focus, disabled).
Tokens
All design attributes (color, typography, layout, etc.) are available as tokens.
93% complete (14 of 15)

Legend:

  • Complete
  • Incomplete
  • Not applicable
Edit this page in GitHub (Permissions required)
Last updated: Dec 01, 2022