Components
Alert
Alert provides users with information that is especially important for them to see and understand. The component is designed to capture users' attention. The text in the alert should be short and clear.
We are working to improve the accessibility documentation for this component. If you have questions or see something that should be prioritised, please contact us on Github or Slack.
Alert in a live region
If you want the alert to be read out dynamically, you must place the Alert inside a live region. The region must wrap around the Alert component, not be placed on the component itself.
Out of the box, Alert is presented to screen reader users as regular static content. For alerts that appear dynamically, you can define a live region for screen readers yourself, but be aware of the behaviour this introduces. You can read more about this in MDN's documentation on ARIA live regions.
Pay particular attention to the fact that the live region — that is, the element with the attribute role="alert", role="status", or aria-live with the value "assertive" or "polite" — must exist on the page before the alert that is to be read out.
For dynamic alerts, it is generally most relevant to use role="alert" for critical alerts or role="status" for less critical alerts, as described in the system notifications pattern. See also the alert role and the status role on MDN.
Do not combine role="alert" and aria-live, since this may cause the alert to be read out twice in VoiceOver (mozilla.org).
You should combine role="status" and aria-live="polite" to maximise compatibility (mozilla.org).
React
const CorrectLiveRegionReactEn = () => { const [showAlert, setShowAlert] = useState(false); return ( <> <Button data-size='sm' variant='secondary' onClick={() => setShowAlert((value) => !value)} > {showAlert ? 'Hide alert' : 'Action that triggers an alert'} </Button> {/* Correct use: role="alert" is placed on the element where the alert appears */} <div role='alert'> {showAlert && ( <Alert data-color='warning'> <Heading level={2} data-size='xs' style={{ marginBottom: 'var(--ds-size-2)', }} > We are unable to save the form </Heading> <Paragraph> We have lost the connection to the server and cannot save the form. Please wait a moment and try again. </Paragraph> </Alert> )} </div> </> ); }; render(<CorrectLiveRegionReactEn />)
For status messages implemented using markup, the following applies:
The result of an action must be coded with one of the following:
- role="status"
- aria-live="polite"
A waiting state must be coded with one of the following:
- role="status"
- aria-live="polite"
Errors must be coded with one of the following:
- role="alert"
- aria-live="polite"
- aria-live="assertive"
Progress in a process must be coded with one of the following:
- role="progressbar"
- the
<progress>element - role="log"
- role="status" and aria-atomic="false"
- aria-live="polite" and aria-atomic="false"