Skip to content

Early previewhamur is not on npm yet. The components are being built in the open, follow along on GitHub.

DisplayReact

Live Announcer

A way to have screen readers speak a message after something happens that the page shows only by sight: an item added to a list, a save that finished, an error.

Rendered by React 19.3.1

import * as React from 'react'
import { LiveAnnouncer, announce } from '@hamur/react/live-announcer'

export default function LiveAnnouncerExample() {
  const [items, setItems] = React.useState<string[]>([])
  const [said, setSaid] = React.useState('Nothing yet')
  return (
    <div className="stack">
      <LiveAnnouncer />
      <div className="actions">
        <button
          className="button"
          type="button"
          onClick={() => {
            setItems((list) => [...list, `Item ${list.length + 1}`])
            announce('Item added')
            setSaid('Item added (polite)')
          }}
        >
          Add item
        </button>
        <button
          className="button danger"
          type="button"
          onClick={() => {
            announce('Could not add item', { politeness: 'assertive' })
            setSaid('Could not add item (assertive)')
          }}
        >
          Add with error
        </button>
      </div>
      <ul className="la-list">
        {items.map((item) => (
          <li key={item}>{item}</li>
        ))}
      </ul>
      <p className="muted">
        Announced: <span className="la-said">{said}</span>
      </p>
    </div>
  )
}
Not measured yetTests passing in React
3.7 KiBSize
Not measured yetMemory
Not measured yetSpeed
[N] commits

Installation

npm i @hamur/react

Not on npm yet. The package goes out under the chosen name.

Anatomy

Import the component and assemble its parts:

<LiveAnnouncer />

Examples

Dialog

A native dialog opened with showModal() that holds its own LiveAnnouncer; its "Save draft" button announces "Draft saved" into it.

LiveAnnouncerDialog.tsx
import * as React from 'react'
import { LiveAnnouncer, announce } from '@hamur/react/live-announcer'

export default function LiveAnnouncerDialogExample() {
  const dialog = React.useRef<HTMLDialogElement>(null)
  const [said, setSaid] = React.useState('Nothing yet')
  return (
    <div className="stack">
      <button className="button" type="button" onClick={() => dialog.current?.showModal()}>
        Open dialog
      </button>
      <dialog ref={dialog} className="la-dialog" aria-labelledby="la-dialog-title">
        <LiveAnnouncer />
        <h2 id="la-dialog-title" className="dialog-title">
          Draft
        </h2>
        <p className="muted">
          Announced: <span className="la-said">{said}</span>
        </p>
        <form method="dialog" className="actions">
          <button
            className="button"
            type="button"
            onClick={() => {
              announce('Draft saved')
              setSaid('Draft saved')
            }}
          >
            Save draft
          </button>
          <button className="button">Close</button>
        </form>
      </dialog>
    </div>
  )
}

API reference

0 props across 1 parts, in React syntax. className, style, render are listed once, under Shared props.

LiveAnnouncerLiveAnnouncer

A visually hidden element holding a polite and an assertive live region, which announce() writes its messages into. Renders a <div>.

Shared props

Every part that renders an element takes these.

Shared props
PropType
classNameCSS class applied to the element, or a function that returns a class based on the component's state.string | ((state: State) => string | undefined)
styleStyle applied to the element, or a function that returns a style object based on the component's state.React.CSSProperties | ((state: State) => React.CSSProperties | undefined)
renderAllows you to replace the component's HTML element with a different tag, or compose it with another component.React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, State>

Keyboard and accessibility

Keyboard

LiveAnnouncer takes no focus and has no keys. The buttons in the examples are plain buttons: Enter and Space press them.

Accessibility

What the parts set
PartSetsSo that
LiveAnnouncerthe hidden style; no role or ARIA on its element; on its two regions role, aria-live and aria-atomic (see above)a message written into a region is read by the screen reader without a focus move

Focus order

  1. LiveAnnouncer is not focusable; focus passes over it.
  2. announce never moves the focus.