Skip to main content
Version: 7.0.0

Known issues

aria-hidden content on VoiceOver​

Content with aria-hidden appears to be sometimes read by VoiceOver on iOS and macOS. It is unclear in which case this happens, and does not appear to be an issue directly related to the library. Refer to this WebKit bug for reference.

aria-labelledby announcement on VoiceOver​

The dialog name associated via aria-labelledby is not read by VoiceOver in Chrome and FireFox (but is in Safari). This peculiar behavior appears when the close button is located before the dialog name.

Making sure the element associated with aria-labelledby comes as a first child of the dialog is a simple workaround to this minor issue.

Shadow DOM​

As reported in issue #322, a11y-dialog fails to account for shadow DOM when trapping the focus. This can be a problem when rendering interactive web components within the dialog.

Mobile issues​

The library relies on aria-modal, a standardized attribute from WAI-ARIA 1.1. Unfortunately, the support for this attribute is not incredible with certain mobile assistive technologies, as reported in issue #408. If that’s an issue for you, you have two equally viable options:

  • Use version 6 of the library which did not rely on the aria-modal attribute. Keep in mind the setup is significantly more complex though — pay attention to the documentation.

  • Use the library in conjunction with the aria-hidden package (<1kb) to combine both implementations for maximum support. Refer to this demo for implementation details.

import A11yDialog from 'a11y-dialog'
import { hideOthers } from 'aria-hidden'

const container = document.querySelector('#my-dialog')
const dialog = new A11yDialog(container)
let registered = false

dialog.on('show', function (event) {
  const undo = hideOthers(container)

  if (!registered) {
    dialog.on('hide', undo)
    registered = true
  }
})