Components

Alert

An alert keeps users informed of important and sometimes time-sensitive changes.

Standard alerts

Informative status

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod.

Warning status

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod.

Success status

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod.

Slim alert

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod.

Alert with no icon

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod. 

<h3 class="site-preview-heading">Standard alerts</h3>

<div class="usa-alert usa-alert--info">
  <div class="usa-alert__body">
    <h4 class="usa-alert__heading">Informative status</h4>
    <p class="usa-alert__text">
      Lorem ipsum dolor sit amet,
      <a class="usa-link" href="javascript:void(0);">consectetur adipiscing</a>
      elit, sed do eiusmod.
    </p>
  </div>
</div>

<div class="usa-alert usa-alert--warning">
  <div class="usa-alert__body">
    <h4 class="usa-alert__heading">Warning status</h4>
    <p class="usa-alert__text">
      Lorem ipsum dolor sit amet,
      <a class="usa-link" href="javascript:void(0);">consectetur adipiscing</a>
      elit, sed do eiusmod.
    </p>
  </div>
</div>

<div class="usa-alert usa-alert--success">
  <div class="usa-alert__body">
    <h4 class="usa-alert__heading">Success status</h4>
    <p class="usa-alert__text">
      Lorem ipsum dolor sit amet,
      <a class="usa-link" href="javascript:void(0);">consectetur adipiscing</a>
      elit, sed do eiusmod.
    </p>
  </div>
</div>

<div class="usa-alert usa-alert--error" role="alert">
  <div class="usa-alert__body">
    <h4 class="usa-alert__heading">Error status</h4>
    <p class="usa-alert__text">
      Lorem ipsum dolor sit amet,
      <a class="usa-link" href="javascript:void(0);">consectetur adipiscing</a>
      elit, sed do eiusmod.
    </p>
  </div>
</div>

<div class="usa-alert usa-alert--emergency" role="alert">
  <div class="usa-alert__body">
    <h4 class="usa-alert__heading">Emergency status</h4>
    <p class="usa-alert__text">
      Lorem ipsum dolor sit amet,
      <a class="usa-link" href="javascript:void(0);">consectetur adipiscing</a>
      elit, sed do eiusmod.
    </p>
  </div>
</div>

<h3 class="site-preview-heading">Slim alert</h3>

<div class="usa-alert usa-alert--info usa-alert--slim">
  <div class="usa-alert__body">
    <p class="usa-alert__text">
      Lorem ipsum dolor sit amet,
      <a class="usa-link" href="javascript:void(0);">consectetur adipiscing</a>
      elit, sed do eiusmod.
    </p>
  </div>
</div>

<h3 class="site-preview-heading">Alert with no icon</h3>

<div class="usa-alert usa-alert--info usa-alert--no-icon">
  <div class="usa-alert__body">
    <p class="usa-alert__text">
      Lorem ipsum dolor sit amet,
      <a class="usa-link" href="javascript:void(0);">consectetur adipiscing</a>
      elit, sed do eiusmod.
    </p>
  </div>
</div>

Guidance

When to use the alert component

  • System status messages. An alert may be a notification that keeps people informed of the status of the system and may or may not require the user to respond. Such notifications may be errors, warnings, and general updates.
  • Validation messages. An alert may be a validation message that informs a user they just took an action that needs to be corrected or a confirmation that a task was completed successfully.

When to consider something else

  • Long forms. On long forms, always include in-line validation in addition to any error messages that appear at the top of the form.
  • 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 action is what they want.

Usability guidance

  • Consider next steps. 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. For example, a notification of a system change may require more contextual information than a validation message. Write the message in concise, human-readable language; avoid jargon and computer code.
  • Be polite. Be polite in error messages — don’t blame the user.
  • Alerts are an opportunity. Users will read a message that helps them resolve an error even if they generally won’t read documentation; include some educational material in your error message.
  • Don’t overdo it. Too many notifications will either overwhelm or annoy the user and are likely to be ignored.
  • Allow a user to dismiss a notification whenever appropriate. USWDS is working on a way to help developers implement a dismissible alert. You can follow our progress on GitHub.
  • Understand the user’s context. Don’t include notifications that aren’t related to the user’s current goal.

Accessibility guidance

  • Don’t visually hide alert messages 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 proper ARIA role. The ARIA role attribute can notify assistive technologies of time-sensitive and important messages. To elevate the importance of the alert, choose the appropriate role from the ARIA roles table and add it to the .usa-alert element.

Alert ARIA roles

Attribute Use Case
role="alert" Important messages that demand the user's immediate attention.
Example: Error alert
role="status" Messages that provide advisory information but do not have the same urgency as alerts.
Example: Success alert
role="region" Messages that provide information the user would want to be able to easily find, but are not important enough to interrupt user workflow.
Example: Informative or warning alert
Note: you must add an appropriate aria-label or aria-labelledby attribute when using this role.

Reference: WAI-ARIA

Using the alert component

Alert settings

Variable Description
$theme-alert-bar-width

Width of the colored bar to the left of the alert.
$theme-alert-font-family

Font family of the alert.
$theme-alert-icon-size

Size of the alert icon.
$theme-alert-padding-x

Padding on the left and right of the alert.
$theme-alert-padding-y

Padding on the top and bottom of the alert.
$theme-alert-text-color

Text color on light backgrounds. Default uses text color set in $theme-text-color.
$theme-alert-link-color

Link color on light backgrounds. Default uses text color set in $theme-text-color.
$theme-alert-text-reverse-color

Text color on dark backgrounds. Default uses reverse text color set in $theme-text-reverse-color.
$theme-alert-link-reverse-color

Link color on dark backgrounds. Default uses reverse link color set in $theme-link-reverse-color.

Alert variants

Variant Description

.usa-alert--emergency

Display an emergency status alert.

.usa-alert--error

Display an error status alert.

.usa-alert--info

Display an informational status alert.

.usa-alert--no-icon

Display an alert without an icon.

.usa-alert--slim

Display a slimmer version of the alert.

.usa-alert--success

Display an success status alert.

.usa-alert--warning

Display an warning status alert.

Package

  • Package usage: @forward "usa-alert";
  • Dependencies: uswds-fonts, usa-icon

Latest updates

Meaningful code and guidance updates are listed in the following table:

Date USWDS version Affects Breaking Description
2024-10-04 3.9.0
  • Styles
 Breaking

Breaking Fixed a bug that caused $theme-site-margins-width to unexpectedly change the alignment inside alert and site alert components. Alignment of alert and site alert components will likely shift from this change. Confirm that your implementation of the component aligns as expected. More information: uswds#5636

2024-03-27 N/A
  • Guidance
 No

Added a note about USWDS developing dismissible alerts. More information: uswds-site#2563

2023-11-20 N/A
  • Guidance
 No

Added documentation for the usa-alert--emergency variant. More information: uswds-site#2149

2023-06-09 3.5.0
  • Styles
 No

Removed redundant and invalid height declaration. More information: uswds#5187

2023-03-09 3.4.0
  • Styles
 No

Updated padding settings to accept any valid spacing token. More information: uswds#5076

2022-10-19 3.2.0
  • Styles
 No

Updated the alignment of alert content to visually match banner content. The site alert component was also updated. More information: uswds#4922

2022-09-26 N/A
  • Accessibility
  • Guidance
 No

Updated instructions for using the ARIA role attribute. More information: uswds-site#1770

2022-04-28 3.0.0
  • Assets
  • JavaScript
  • Styles
 Breaking

Breaking Updated to Sass module syntax and new package structure. More information: uswds#4656

2021-03-17 2.11.1
  • Assets
 No

Restored missing white icons. Restored error--white, info--white, and warning--white icons. More information: uswds#4106

2021-03-17 2.11.0
  • Assets
  • Styles
 No

Provided better support for color icons that adapt to theme settings. Now the color of the alert icon will update automatically to adapt to the alert background, or to the color of the alert text. More information: uswds#4079

2021-03-17 2.11.0
  • Styles
 No

Added the $theme-alert-padding-y setting. More information: uswds#4079