Component API

Announce

When dynamically changing content on a page, it is important that all users become aware of these changes. While changes may be visually apparent to users who cans see the page, they may not be clear to users of assistive technology. The Announce component uses the aria-live attribute to to expose dynamic content to those using screen readers.

Basic Usage

This content will be read by a screen reader when it changes.

Initial content

import React from 'react';
import { Announce, Button } from 'react-magma-dom';

export function Example() {
  const [announceContent, setAnnounceContent] = React.useState<string>(
    'Initial content'
  );

  function updateAnnounceContent() {
    setAnnounceContent('New content replacing the initial content');
  }

  return (
    <>
      <p>This content will be read by a screen reader when it changes.</p>
      <p>
        <Button onClick={updateAnnounceContent}>Update content</Button>
      </p>
      <Announce>
        <p>{announceContent}</p>
      </Announce>
    </>
  );
}

Politeness

The Announce component takes an optional politeness prop, that accepts the following values: assertive, off, and polite. The default value is polite. This sets the value of the aria-live attribute and is used to set the priority with which screen reader should treat updates to live regions.

When polite is used, assistive technology will notify a users of a change after the current task is complete. When assertive is used, assistive technologies will notify the user immediately, possibly interrupting the current task. Using off will silence these updates, so they will not be read.

This content will be read by a screen reader immediately when it changes.

Initial assertive content

This content will be not read by a screen reader when it changes.

Initial off content

import React from 'react';
import { Announce, Button } from 'react-magma-dom';

export function Example() {
  const [
    announceContentAssertive,
    setAnnounceContentAssertive,
  ] = React.useState<string>('Initial assertive content');
  const [announceContentOff, setAnnounceContentOff] = React.useState<string>(
    'Initial off content'
  );

  function updateAnnounceContentAssertive() {
    setAnnounceContentAssertive(
      'New content replacing the assertive initial content'
    );
  }

  function updateAnnounceContentOff() {
    setAnnounceContentOff('New content replacing the off initial content');
  }

  return (
    <>
      <p>
        This content will be read by a screen reader immediately when it
        changes.
      </p>
      <p>
        <Button onClick={updateAnnounceContentAssertive}>
          Update assertive content
        </Button>
      </p>
      <Announce politeness="assertive">
        <p>{announceContentAssertive}</p>
      </Announce>
      <hr />
      <p>This content will be not read by a screen reader when it changes.</p>
      <p>
        <Button onClick={updateAnnounceContentOff}>Update off content</Button>
      </p>
      <Announce politeness="off">
        <p>{announceContentOff}</p>
      </Announce>
    </>
  );
}

Announce Props

This component uses forwardRef. The ref is applied to the Announce container div element.

All of the global HTML attributes can be provided as props and will be applied to the wrapping div element that gets rendered.

= required prop

Property	Type	Default	Description
children Required	ReactNode	-	The content of the component
politeness	enum, one of: `AnnouncePoliteness.assertive` `AnnouncePoliteness.off` `AnnouncePoliteness.polite`	AnnouncePoliteness.polite	Value of the `aria-live` attribute
testId	string	-	Test ID attached to an internal element as `data-testid` for consumer testing