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.
Error status
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod.
Emergency 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
<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 appropriaterole
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 oder 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. |
$theme-alert-link-color
|
Link color on light backgrounds. |
$theme-alert-text-reverse-color
|
Text color on dark backgrounds. |
$theme-alert-link-reverse-color
|
Link color on dark backgrounds. |
Alert variants
Variant | Description |
---|---|
|
Display an emergency status alert. |
|
Display an error status alert. |
|
Display an informational status alert. |
|
Display an alert without an icon. |
|
Display a slimmer version of the alert. |
|
Display an success status alert. |
|
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 | Description |
---|---|---|---|
2024-03-27 | K.A. |
|
Added a note about USWDS developing dismissible alerts. More information: uswds-site#2563 |
2023-11-20 | K.A. |
|
Added documentation for the |
2023-06-09 | 3.5.0 |
|
Removed redundant and invalid height declaration. More information: uswds#5187 |
2023-03-09 | 3.4.0 |
|
Updated padding settings to accept any valid spacing token. More information: uswds#5076 |
2022-10-19 | 3.2.0 |
|
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 | K.A. |
|
Updated instructions for using the ARIA |
2022-04-28 | 3.0.0 |
|
Breaking Updated to Sass module syntax and new package structure. More information: uswds#4656 |
2021-03-17 | 2.11.1 |
|
Restored missing white icons.
Restored |
2021-03-17 | 2.11.0 |
|
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 |
|
Added the |