React hooks and components for managing ARIA live regions. Announce dynamic content changes to screen reader users with a simple, declarative API.

npm install @umxr/react-aria-live

Wrap your app with LiveRegionProvider and use the useAnnounce hook to make announcements:

import { LiveRegionProvider, useAnnounce } from '@umxr/react-aria-live';

function App() {
  return (
    <LiveRegionProvider>
      <SaveButton />
    </LiveRegionProvider>
  );
}

function SaveButton() {
  const announce = useAnnounce();

  const handleSave = async () => {
    await saveData();
    announce('Document saved successfully');
  };

  return <button onClick={handleSave}>Save</button>;
}

Context provider that manages live region announcements. Wrap your app with this component.

<LiveRegionProvider clearOnUnmount={true}>{children}</LiveRegionProvider>

Hook for making announcements programmatically.

const announce = useAnnounce();

// Polite announcement (default)
announce('Items updated');

// Assertive announcement (interrupts)
announce('Error: Failed to save', { priority: 'assertive' });

// With delay
announce('Auto-saved', { delay: 1000 });

// Clear queue before announcing
announce('New message', { clearQueue: true });

Options:

Hook for accessing the announcement queue state.

const { queue, clear, isPending } = useAnnouncementQueue();

Declarative component for content that should be announced when it changes.

<LiveRegion priority="polite" atomic>
  {statusMessage}
</LiveRegion>

Component for one-off announcements without rendering visible content.

{
  isSuccess && <Announce message="Form submitted successfully" />;
}

Renders live region elements that can be placed inside modals or other focus-trapped containers.

By default, the library creates announcer elements at the document body level. However, screen readers may not announce content from live regions outside a focused modal. Use the Announcer component inside your modal to ensure announcements are heard.

import { Announcer } from '@umxr/react-aria-live';

function Modal({ children }) {
  return (
    <div role="dialog" aria-modal="true">
      <Announcer />
      {children}
    </div>
  );
}

How it works:

• All Announcer components subscribe to the same announcement queue
• When useAnnounce() is called, ALL mounted announcers receive the message
• The screen reader hears the announcer that's in the active focus context

Pre-configured components for common patterns:

Assertive announcements with role="alert".

<Alert>Payment failed. Please try again.</Alert>

Polite status updates with role="status".

<Status>{itemCount} items in cart</Status>

Sequential content like chat messages with role="log".

<Log>
  {messages.map((m) => (
    <p key={m.id}>{m.text}</p>
  ))}
</Log>

The package exports test utilities for verifying announcements in your tests:

import {
  getAnnouncements,
  clearMockAnnouncements,
} from '@umxr/react-aria-live/test';

test('announces on save', async () => {
  render(<SaveButton />);

  await userEvent.click(screen.getByRole('button'));

  expect(getAnnouncements()).toContain('Document saved');
});

Test utilities:

1. Use polite by default - Reserve assertive for critical, time-sensitive information
2. Keep messages concise - Screen reader users benefit from brief, clear announcements
3. Avoid duplicate announcements - The library automatically deduplicates within 150ms
4. Test with real screen readers - Automated tests can't catch all accessibility issues

• Chrome (latest 2 versions)
• Firefox (latest 2 versions)
• Safari (latest 2 versions)
• Edge (latest 2 versions)

MIT