Alert

Examples

Additional guidance for VA

Additional uses of an alert

• To notify users about the status of the system:
  • 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. For application-level maintenance, review the downtime notifications guidance.
  • 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.
• To respond to a user action:
  • 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.
• 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.
• Unprompted and in-page alerts. On the website, consider the Alert - Expandable component to draw attention to important information on the page that is not a response to user feedback. On the mobile app, use the expandable variation of the Alert component.

Additional reasons to consider something else

Web and mobile

• 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 Details 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 on web. Most system messages related to maintenance are handled by the Banner - Maintenance component.
• As the only content on a page. An Alert should not be the only, or the majority of, content on a page. Reduce the length of the alert and include context in the content well of the page.
• For highlighting a single task that is urgent, time-sensitive, or required. Consider the Critical Action component when you want to highlight a single task that will otherwise block the user from proceeding. This can be used within cards or service list items.

Mobile app only

• Use native components. On the mobile app, always consider a native component before using an in-content Alert:
  • Action Sheet. When the user takes an action in which the system needs to clarify their intent, use an action sheet (for both iOS and Android) to offer the user a choice in how to proceed.
  • Alert/dialogue. When the user chooses to do something that has serious consequences, use a native modal alert (for iOS) or dialogue (for Android) to present the user with critical information related to that action.
  • Snackbar. If a user action triggers an API call that is successful or results in an error, consider using a Snackbar in addition to or instead of an Alert. The snackbar may allow users to take an action on the feedback such as trying again or undoing the action.
• Sub-alerts on the page. On the mobile app, do not use sub-alerts.

When to use a Slim alert

Web

All of the above standard alert uses cases apply however, use of a Slim alert in place of a standard alert is only appropriate when used with one of these additional constraints:

• Immediate feedback to the user. When your application is using Javascript to provide an immediate response to the user without a full page load.
• Sub-alerts on the page. When your page has more than 1 alert and you are using the Standard and Slim alerts to create a hierarchy of alerts within the page. This does not mean stacking alerts on top of one another, this means placing them appropriately throughout the page. It can also be appropriate to convey multiple statuses using a combination of headers, text, and the Slim alert variation. An example of a sub-alert is the Autosave alert.
• Within cards for information that is specific to that card. Alerts within cards would be used in cases where an alert outside of the card would cause issues for hierarchy and clarity, especially if there are multiple cards within a collection.

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.
• When there are multiple alerts on the page, order them by severity with the most critical being first and ideally top of the page.
• 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 Details component.
• Messaging should be direct, concise, and in plain language.
• Standard alerts must contain headings as opposed to Slim alerts which do not contain headings.

Choosing between alert statuses

Choose the appropriate status based on the nature of the message and its urgency. Consistency in status usage across VA.gov helps Veterans quickly understand the nature of messages.

Informational (info)

Use informational alerts to provide helpful context or supplementary information that doesn’t require immediate action.

• General announcements. Information the user should be aware of but that doesn’t indicate something went wrong or was completed.
• Guidance and tips. Helpful context for completing a task.
• Status updates. Neutral updates about the state of something, such as “Your application is being processed.”

Warning

Use warning alerts when there are potential negative consequences or when something may go wrong if the user doesn’t take action.

• Potential issues. When something might prevent the user from completing their goal if not addressed.
• Time-sensitive information. Deadlines or expiration dates that require attention.
• Proceed with caution. When an action has consequences the user should understand before proceeding.

Success

Use success alerts to confirm that a user-initiated action completed successfully. The key distinction is that the user took an intentional action and the system is confirming it worked.

• Task completion. Confirming that a form submission, save, or other intentional action was successful.
• Updates confirmed. When the user updates their information and the change is saved.
• Explicit saves. When the user actively saves their progress.

When autosave completes successfully: Autosave is an example of a system-initiated action that still uses a success alert because the system successfully preserved the user’s work. Autosave is currently being researched and the handling of autosave messages may change in future. At the moment, it is okay to have two success alerts on the page if one of them is the autosave alert in a form flow.

Error

Use error alerts to indicate that something has gone wrong and typically requires the user to take corrective action.

• Validation errors. When form input doesn’t meet requirements.
• Failed actions. When a submission, save, or other action didn’t complete.
• System failures. When the system encountered an error that affects the user’s ability to complete their task.
• Access issues. When the user can’t access something they’re trying to reach.

Choosing between warning and error

Use warning when something might go wrong or requires attention before proceeding. Use error when something has gone wrong and needs to be fixed. Warnings are preventative; errors are reactive.

Handling multiple alerts

Displaying multiple alerts should be avoided. However, when you need to display multiple alerts on a page, follow the general alert usage guidance above (including ordering alerts by severity and avoiding stacking alerts). In addition:

• Create visual hierarchy. When multiple alerts are necessary, use a Standard alert for the primary message and Slim alerts for secondary messages.

Links within alerts

• Use an action link when a link is needed. The preferred usage of links in an alert is the action link, which is a single link directing the user to a clear next step or call-to-action.
  • A Link - Active style is an acceptable variation.
• Use the correct link variation for specific actions. For example, use the Link - Directions variation when linking to a Maps application for a facility location. Use the Telephone component when linking to a phone number.
• Don’t use bold text for standard links within alert messages. The blue color and underline already provide sufficient visual distinction. Follow the same link styling guidelines and bold text guidelines used elsewhere on VA.gov. Note that standard links are often a secondary action and appear alongside buttons, see Alert - Sign-in for examples.

Placement

Web

Standard Alert

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

Slim alert

• Slim alerts related to a form field or section should be placed below the label, legend, or section header.
• The Info variation of the Slim alert can be placed between sections.
• Save-in-progress success and error Slim 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.
• Slim alerts within cards should be placed above the call-to-action (CTA).

Mobile app

Standard Alert

• Alerts always appear near the top of the screen.

Choosing between variations

Web

• Use the standard Alert variation in most use cases and within static content pages. Slim alerts are not available in Drupal.
• Use the Slim alert variation for immediate feedback within forms and applications. Slim 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.

Mobile app

• Use standard alerts for most use cases.
• Use expandable alerts when the information is not a response to user feedback.
• Use dismissible alerts when the content is informational and not specific to the user or their interaction. For example, displaying “what’s new” content in the app.

Code usage

Content considerations

• Keep alert and error message titles (headings) to 50 characters (with spaces) when possible. Titles should follow the general guidelines for page and section titles.
  Learn more in the Page titles and section titles section of the content style guide
• Keep slim alerts to 100 characters (with spaces) when possible. If you have a slim alert that’s longer than 100 characters, contact the VA.gov content and IA team. The team will work with you to edit the alert or determine if we need to make an exception (up to 150 characters).
• Acknowledge when an issue is our fault. Don’t place blame on the person, even if the person’s actions caused the error.
• Don’t say “please” in alert and error messages when making a request.
• Include brief educational material in your alert and error messages when needed. People may not read documentation, but they’re more likely to read a message that helps them resolve an error.
• Don’t overdo it with alerts. Too many notifications can overwhelm or annoy the person, who may then ignore the messages.
• Don’t use jargon or computer code in the message.

Accessibility considerations

Additional accessibility considerations for VA

• No auto-dismissal. Don’t automatically dismiss an alert based on a timer or time limit.
• Elements within an Alert that should receive focus. Focusable elements within an Alert should include: heading, body copy, phone numbers, and buttons.

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 doesn’t need a role.
• Important, time-sensitive information: Use role=”alert”. Use this role on alert components that appear after a user interaction. Alerts are assertive live regions, so setting role="alert" is equivalent to setting aria-live="assertive" and aria-atomic="true".

    <va-alert role="alert" ...>...</va-alert>
  

  • This is for live updates to a page that would not get noticed otherwise. Updates to a page can occur without the user refreshing the page, so these may go unnoticed when using assistive technologies. role="alert" ensures assistive technology announces these updates and keeps the user informed.
  • Because this can be intrusive to the user experience, this should be used sparingly for information that requires the user’s immediate attention.
  • Interactive alerts: Use role=”alertdialog” instead. For alerts that fit the criteria of role="alert", but also contain content requiring user interaction, use role="alertdialog" instead of role="alert". For example, expecting the user to acknowledge the alert by closing it before proceeding.

    <va-alert role="alertdialog" ...>...</va-alert>
    

• Advisory information, not important enough to have an alert role: Use role=”status”. Use this role on alert components that appear after a user interaction. This allows users with assistive tech to be notified of the change, but won’t immediately interrupt them from the current task. Elements with the role=status have an implicit aria-live=polite and an implicit aria-atomic=true.

    <va-alert role="status" ...>...</va-alert>
  

• For must-read information that is present on page load, consider using a Summary box instead of an alert.

More on ARIA: alert role, ARIA: status role.

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.

Mobile

• Use appropriate component type. Alerts should only be used when appropriate to do so. Do not use in-content Alerts when a native alert would be best (i.e., native alert, dialogue, action sheet, snackbar, etc.).
• Announce drawer states. Alerts that have expanded / closed states must be announced by a screen reader.
• No disabled buttons. No buttons should be disabled within an Alert. All interactive elements must be actionable.
• Use appropriate labels. accessibilityLabel and accessibilityLabelledBy should be used where appropriate.

Related

• Alert - Expandable
• Banner
• Snackbar (Mobile app)

Component checklist

Provide feedback

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