Package Exports

react-a11y-dialog

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (react-a11y-dialog) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

React A11yDialog

react-a11y-dialog is a thin React component 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.

Special thanks to Moritz Kröger (@morkro) for his 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

Name	Type	Required	Default	Description
`id`	`string`	true	—	Expand The HTML `id` attribute of the dialog element, internally used by a11y-dialog to manipulate the dialog.
`title`	`node`	true	—	Expand The title of the dialog, mandatory in the document to provide context to assistive technology. Could be hidden with CSS (while remaining accessible).
`dialogRoot`	`string`	false	`document.body`	Expand The container for the dialog to be rendered into (React portal’s root).
`dialogRef`	`function`	false	`() => {}`	Expand A function called when the component has mounted, receiving the instance of A11yDialog so that it can be programmatically accessed later on.
`titleId`	`string`	false	`${props.id}-title`	Expand The HTML `id` attribute of the dialog’s title element, used by assistive technologies to provide context and meaning to the dialog window.
`closeButtonLabel`	`string`	false	Close this dialog window	Expand The HTML `aria-label` attribute of the close button, used by assistive technologies to provide extra meaning to the usual cross-mark.
`closeButtonContent`	`node`	false	`\u00D7` (×)	Expand The string that is the inner HTML of the close button.
`closeButtonPosition`	`string`	false	first	Expand Whether to render the close button as first element, last element or not at all. Options are: `first`, `last` and `none`. ⚠️ Caution! Setting it to `none` without providing a close button manually will be a critical accessibility issue.
`classNames`	`object`	false	{}	Expand Object of classes for each HTML element of the dialog element. Keys are: `container`, `overlay`, `dialog`, `title`, `closeButton`. See a11y-dialog docs for reference.
`role`	`string`	false	dialog	Expand The `role` attribute of the dialog element, either `dialog` (default) or `alertdialog` to make it a modal (preventing closing on click outside of `ESC` key).

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-element'>
        <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

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={dialog => (dialog.current = dialog)}
        title='The dialog title'
      >
        <p>Some content for the dialog.</p>
      </A11yDialog>
    </div>
  )
}

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