Figma
StorybookExamples
Informational (Default)
The informational alert provides supplementary information or highlights a tool or step available to the user to help them complete their current action or task. It’s non-critical or optional messaging that gives guidance on what the user needs to do to proceed.
Error
The error alert informs users of an error or critical failure. This alert is often used to block users from proceeding until they resolve the issue including system alerts.
Warning
The warning alert informs users that their entry or selection may have unexpected or undesirable results, some of which may not be easily undone.
Success
The success alert confirms the successful completion of a step or task, or receipt of information provided by the user.
Lightweight
The lightweight alert highlights information that is not as urgent as informational alerts.Guidance
When to use
Informational
On Forms: To provide key supplementary or contextual information to support the successful completion of tasks or aid overall comprehension. On Static Pages: To highlight recent, critical changes.
Examples:
- To provide additional information such as explanations of criteria the user needs to meet
- To highlight new information available
Lightweight informational alert may be used if information is helpful, but not critical or necessary to complete the task.
Error
On Forms: To draw focus to an error or an incomplete task by prompting the user to review or take other action.
Examples:
- To alert a user of missing form entry
- To alert a user of incorrect form entry
- To alert a user of broader system issues
Never use error alerts on static pages.
Warning
On Forms: To call out or notify a user of risk or important information prior to completing the action.
On Static Pages: To notify users of scheduled website maintenance or unexpected system outage.
Examples:
- To warn a user of potential negative consequences of a certain action
- To warn a user of unintended results
- To encourage a user to double check their choices
- To highlight information that a user should be aware of
Success
On Forms: To confirm that a task was completed successfully.
Examples:
- To confirm submission of an application
- To offer a user positive feedback, such as a congratulatory note
- To guide the user to the next step in a multi-step process
Never use success alerts on static pages.
Guidelines
- Don’t overdo it—Limit alerts to no more than 2 per screen. Too many notifications won’t be read, as they can overwhelm and annoy the user.
- Only include notifications that relate to the user’s current goal.
- Be mindful of other elements on the page that may compete for the user’s attention.
- On forms, always include in-line validation in addition to any error alerts that appear at the top of the form.
- If the error alert relates to specific text fields, also display the impacted fields in an error state.
When to consider alternatives
- For less critical messages or less-urgent information, consider tooltips, hint text, or inline help text.
- When the goal is to guide user input, utilizing hint text or inline help can be more effective in providing real-time guidance within form fields.
- 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.
Display & behavior
- Alerts may be displayed statically on a page, appearing immediately when the webpage is first loaded, or dynamically loaded on a page, appearing based on specific conditions or user interactions, like clicking a button, submitting a form, or fulfilling certain criteria on the page.
- Alerts with icons are preferred. An alert doesn’t need to include an icon if it requires a large amount of content. Such instances should be rare. Validate the design and spacing on mobile to help make this decision.
- 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.
- Don’t use alerts with a timer or dismiss button.
Content guidelines
Guidelines
- Keep alerts short—Use the fewest words possible to convey the concept or issue.
- Best practice is no more than 2-3 short sentences.
- If longer, consider adding a link to a help drawer to provide more details.
- Use plain language, active voice, and imperative style when providing directions.
- Avoid jargon and computer code, like “Message 1234,” or code snippets, such as -h, - p 8080, -d /var/www/html.
- Alert content can include:
- A heading (not required)
- Navigational links
- “Trigger words” to open help drawer for more details o Bulleted or numbered lists
- Get more details from 18 F on writing in active voice.
Heading content
- Alert headings are optional, but preferred. They draw attention and frame the information in the alert.
- Bold alert headings and use sentence case.
- Don’t include punctuation, unless it’s a question.
Content for error alerts
- Help the user correct the error —Don’t place blame on the user.
- Keep error alerts short, using the fewest words possible to describe what went wrong and what the user needs to do.
- Alerts support various types and lengths of content from ~45 to ~80 characters wide.
- When writing error alerts, use:
- Plain language and active voice. Use contractions.
- Imperative style for directions to correct the error or action to take.
- Don’t use words like "please" or "sorry," or informal language like “oops.”
- Sentence case and include punctuation. Don’t use exclamation points.
- If action to correct error has multiple steps or is complex, consider adding trigger text for a help drawer to provide more details.
- Get details about inline error messages that pair with error alerts.
Accessibility
Accessibility
- Use alerts sparingly to avoid creating too much "noise" in screen readers, making it difficult to understand the overall layout of the page.
- Place alerts in an effective location to draw attention even when CSS is turned off. Content helps also to make the importance of the message clear.
- Immediately notify users relying on assistive tech, like screen readers, when an alert appears.
- Users who are using a keyboard to navigate the page must be able to access the alert and its content in the right order.
- Don’t visually hide alert messages on the page and then make them visible when needed. Users of older assistive technologies may still be able to perceive the alert messages even if they aren’t currently applicable.
- If you have multiple alert components on a page, tailor the accessible text to differentiate between each by using an aria-label or aria-labeled by attribute.
Accessibility for dynamic alerts
If dynamically loading an alert, be mindful of when the alert displays on the page.
- For example, an alert could appear on a page due to an error or progressive disclosure. Synchronize the visual presentation of dynamically loaded content with its auditory presentation by screen readers.
- Errors need immediate attention, but content through progressive disclosure may not.
When a user's actions require dynamically displaying an alert, such as with success or error states, inject the alert inside an already existing
<div>witharia-live="polite"andaria-relevant="additions removals"orrole="alert". These ARIA attributes ensure screen readers will announce alerts that have been added or updated dynamically.- Your empty
<div>on page load would appear as:
<div aria-live="polite" aria-relevant="additions removals"></div>- When the user performs an action that displays an alert, add the alert to the existing
<div>:
<div aria-live="polite" aria-relevant="additions removals"> <div role="region" class="ds-c-alert ds-c-alert--error">...</div> </div>- Your empty
The value of the
aria-liveattribute is used to update assistive technologies on the degree of importance.aria-live="polite"will notify users of updates but generally do not interrupt the current task, with the updates having a low priority.aria-live="assertive"will immediately notify the user, potentially clearing the speech queue of previous updates. Don't use the assertive value unless the interruption is imperative.aria-relevant="additions removals"(tailored to the appropriate value) will communicate the types of changes that occurred to an aria-live region. You only need to inform assistive technologies of content removal when the removal represents an important change.
If you choose to shift focus to the alert, be mindful that using other techniques like
role="alert", andaria-live="polite"will cause some browser and screen reader combinations to read out the content more than once. Typically, shifting focus alone will be enough to alert screen readers of the content.
Accessibility testing
General
- The alert should have a unique, accessible name.
- 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 DOESN'T 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.
Report an accessibility bug
If you encounter a bug with the accessibility of the alert component, refer to our refer to our bug reporting confluence page and use CMSDS bug reporting workflow in our #cms-design-system-team slack channel.
Code
React
Review Storybook for React guidance of this component.
Web Component
Go to 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.
Component maturity
For more information about how we tested and validated our work for each checklist item, read our component maturity documentation.