React A11yDialog

react-a11y-dialog provides a thin (~600b) React component and hook for a11y-dialog relying on React portals to ease the use of accessible dialog windows in React applications.

Version compatibility:

• For React versions before 16, use react-a11y-dialog@2.0.0.
• For React versions before 16.8, use react-a11y-dialog@4.2.0.
• For React 16.8 and later, use the latest version

Special thanks to Moritz Kröger (@morkro), Mayank (@mayank99) and EJ Mason (@mxmason) for their kind help in making that library better.

• Install
• API
• Hook
• Server-side Rendering
• Mocking portals in tests
• Example

Install

npm install --save react-a11y-dialog

API

Hook

The library exports both A11yDialog, a React component rendering a dialog while performing the a11y-dialog bindings under the hood, and a useA11yDialog hook providing only the binding logic without any markup.

Using the hook can be handy when building your own dialog. Beware though, it is an advanced feature. Make sure to stick to the expected markup.

import { useA11yDialog } from 'react-a11y-dialog'

const MyCustomDialog = props => {
  // `instance` is the `a11y-dialog` instance.
  // `attr` is an object with the following keys:
  // - `container`: the dialog container
  // - `overlay`: the dialog overlay (sometimes called backdrop)
  // - `dialog`: the actual dialog box
  // - `title`: the dialog mandatory title
  // - `closeButton`:  the dialog close button
  const [instance, attr] = useA11yDialog({
    // The required HTML `id` attribute of the dialog element, internally used
    // a11y-dialog to manipulate the dialog.
    id: 'my-dialog',
    // The optional `role` attribute of the dialog element, either `dialog`
    // (default) or `alertdialog` to make it a modal (preventing closing on
    // click outside of ESC key).
    role: 'dialog',
  })

  const dialog = ReactDOM.createPortal(
    <div {...attr.container} className='dialog-container'>
      <div {...attr.overlay} className='dialog-overlay' />

      <div {...attr.dialog} className='dialog-content'>
        <p {...attr.title} className='dialog-title'>
          Your dialog title
        </p>

        <p>Your dialog content</p>

        <button {...attr.closeButton} className='dialog-close'>
          Close dialog
        </button>
      </div>
    </div>,
    document.body
  )

  return (
    <>
      <button type='button' onClick={() => instance.show()}>
        Open dialog
      </button>
      {dialog}
    </>
  )
}

Server-side rendering

The A11yDialog React component does not render anything on the server, and waits for client-side JavaScript to kick in to render the dialog through the React portal.

Mocking portals in tests

When you’re using react-a11y-dialog in your unit tests, it might be necessary to mock React Portals and inject them to the root DOM before your tests are running. To accomplish that, create helper functions that attach all portals before a test and remove them afterwards.

const ROOT_PORTAL_IDS = ['dialog-root']

export const addPortalRoots = () => {
  for (const id of ROOT_PORTAL_IDS) {
    if (!global.document.querySelector('#' + id)) {
      const rootNode = global.document.createElement('div')
      rootNode.setAttribute('id', id)
      global.document.body.appendChild(rootNode)
    }
  }
}

export const removePortalRoots = () => {
  for (const id of rootPortalIds) {
    global.document.querySelector('#' + id)?.remove()
  }
}

And then use them in your tests.

describe('Testing MyComponent', () => {
  beforeAll(() => addPortalRoots())
  afterAll(() => removePortalRoots())
})

Example

The following example is a minimal setup of react-a11y-dialog. Additionally, you will need to add the required styles as per the recommendations from the a11y-dialog styling docs. How you integrate these styles is left to your discretion and depends on the styling layer you’ve chosen for your project (classes, inline styles, CSS Modules, CSS-in-JS…). For anything but inline styles, styles will typically need to be passed via the classNames object prop, and as such will end up being applied to the elements rendered by React.

import { A11yDialog } from 'react-a11y-dialog'

const App = props => {
  const dialog = React.useRef()

  return (
    <div>
      <button type='button' onClick={() => dialog.current.show()}>
        Open the dialog
      </button>

      <A11yDialog
        id='my-accessible-dialog'
        dialogRef={instance => (dialog.current = instance)}
        title='The dialog title'
      >
        <p>Some content for the dialog.</p>
      </A11yDialog>
    </div>
  )
}

ReactDOM.render(<App />, document.querySelector('#root'))

Migrating to v7

Version 7 now relies on a11y-dialog@8.0.0. It should be largely backward compatible with version 6 though.

• Make sure to read the a11y-dialog migration guide to adjust your a11y-dialog usage.
• Typing has been consolidated.
• Distribution has been improved (CJS + ESM, both normal and minified).
• The A11yDialogInstance type is re-exported from a11y-dialog for convenience.

Migrating to v6

Version 6 now relies on a11y-dialog@7.0.0. See the a11y-dialog migration guide. Most notable changes requiring some update:

• The inner container is no longer a thing.
• The appRoot prop is no longer a thing.
• The dialogRoot prop now defaults to document.body.
• The useDialogElement prop is no longer supported (<dialog> is no longer supported).