# Alert Alerts give feedback to users, provide critical information, and/or offer key supplementary details about a task. ## 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 - [Plain Language Guide: Writing (Digital.gov)](https://digital.gov/guides/plain-language/writing) #### 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.](https://design.cms.gov/components/inline-error/) ### 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 `
` with `aria-live="polite"` and `aria-relevant="additions removals"` or `role="alert"`. These ARIA attributes ensure screen readers will announce alerts that have been added or updated dynamically. - Your empty `
` on page load would appear as: ```html
``` - When the user performs an action that displays an alert, add the alert to the existing `
`: ```html
...
``` - The value of the `aria-live` attribute 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"`, and `aria-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](https://www.w3.org/WAI/ARIA/apg/practices/names-and-descriptions/). - 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)](/components/modal-dialog/), 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 have access to CMS internal tools, report accessibility issues through the [CMSDS bug reporting workflow in Confluence](https://confluence.cms.gov/pages/viewpage.action?pageId=1138979323). If you do not have access to CMS internal tools, report accessibility issues using the [public GitHub issue template](https://github.com/CMSgov/design-system/issues/new?template=propose-a-new-item-for-the-cms-design-system.md).