Examples

Informational (Default)

Error

Warning

Success

Lightweight

Guidance

Usage

• Don’t overdo it — too many notifications will either overwhelm or annoy the user and are likely to be ignored.
• Write the message in concise, human readable language; avoid jargon and computer code.
• Don’t include notifications that aren’t related to the user’s current goal.
• 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.
• Be mindful of other elements on the page that may compete for the user’s attention.

When to use

• As a validation message that alerts someone that they just did something that needs to be corrected or as confirmation that a task was completed successfully.
• As a callout or notification for important or timely information. This includes errors, warnings, and general information.
• Drawing focus to an error or an incomplete task by prompting the user to review or take other action.
• Confirming the successful competition of a task.
• Providing key supplementary or contextual information to support the successful completion of tasks or aid overall comprehension.

When to consider alternatives

• On long forms, always include in-line validation in addition to any error messages that appear at the top of the form. When possible, simplify forms by rewriting and where possible, splitting long forms across multiple pages
• 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.
• When you need to display content that isn't related to the user’s current goal.

When the alert is for an error:

• Be polite in error messages — don’t place blame on the user.
• Users generally won’t read documentation but will read a message that helps them resolve an error; include some educational material in your error message.
• If the error relates to specific text fields, give these fields an error state as well.

Display & behavior

• Alerts are static and shouldn't be associated with a timer or dismiss button.
• Can be displayed statically on page load or dynamically loaded.
• 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.

Accessibility

• Use alerts sparingly as to avoid creating too much "noise" in screen readers, making it difficult to understand the overall layout of the page.
• Users who are viewing the content need it to be placed in an effective location and to draw attention even when CSS is turned off. Content can help here too, using word choices that make the importance of the message clear.
• Users who hear this content through assistive technology, such as a screen reader, will need to be alerted when the alert component visually appears, and that can be done using aria-live.
• Users who are using a keyboard to navigate the page will need to be able to access the alert and its content in the right order.
• Do not 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.
• Use the ARIA role="alert" to inform assistive technologies of a time-sensitive and important message that is not interactive. If the message is interactive, use the role="alertdialog" instead. Both include an implicit use of aria-live="assertive". Refer to the Dialog component’s full documentation when using role="alertdialog".
• If you have multiple alert components on a page, tailor the accessible text to differentiate between each by using an aria-label or aria-labelledby attribute.

Accessibility testing

General

• The alert should have a unique, accessible name

  You are leaving design.cms.gov.

  You're about to connect to a third-party site. Select CONTINUE to proceed or CANCEL to stay on this site.

  Learn more about links to third-party sites.

  ContinueCancel
  .
• The alert purpose should be clear in the context of the whole page.

Keyboard testing

• When using features that trigger the display of an alert, I should see or hear the alert announced, but focus DOES NOT transfer automatically when the alert appears.
• When using features that trigger the display of an alert dialog (modal), I should see or hear the alert announced, and focus DOES transfer automatically when the alert appears.

Screen reader testing

When using a screen reader (NVDA, JAWS, VoiceOver, TalkBack):

• Using features that trigger the display of an alert:
  • The alert is announced when it appears
  • It identifies itself as an alert
• Navigating the page announces the accessible name of the alert, followed by the alert content.

Learn more

• 18F Content Guide - Active voice

  You are leaving design.cms.gov.

  You're about to connect to a third-party site. Select CONTINUE to proceed or CANCEL to stay on this site.

  Learn more about links to third-party sites.

  ContinueCancel

Component maturity

Code

React

See Storybook for React guidance of this component.

Web Component

See Storybook for Web Component guidance of this component.

Style customization

The following CSS variables can be overridden to customize Alert components:

Analytics

This component has analytics tracking available. Please see our developer documentation about using analytics in the design system.