Alert

What you need to check

Alert that appears or updates after the page has loaded must be automatically announced by screen readers.

Use role="alert" for critical messages that require immediate attention. Use role="status" for less critical messages.

Alert must be placed so that it follows the reading order.

This means the Alert must appear in the DOM in a way that provides a logical reading order for screen readers. If the Alert has a heading, the heading level must be correct in the page structure.

Alert text must explain what happened and what it means for the user.

Example: “Your changes have been saved” or “An error occurred while saving. Please try again later”. Not just: “Error” or “Warning”.

See the system notifications pattern for guidance on writing.

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).

Unable to parse html

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 />)