Important: This website does not attempt to establish a standard for how assistive technologies must behave. Read the FAQ for more information. Additionally, this is a work in progress. Please submit feedback or suggestions.

dialog role (aria)

Screen Reader support level: partial (36/44)

On this page

About this feature

A dialog is a descendant window of the primary window of a web application. For HTML pages, the primary application window is the entire web document, i.e., the body element.

Age of results

Results across all tests for this feature range from 10 months ago to 8 years ago. Detailed dates and version information can be found in associated tests.

Caution

Failing or partial results may be out of date. The oldest result is from 3 years ago. Consider running the associated tests and contributing results.

Expectations

What are expectations?

Screen Reader support by expectation

ExpectationJAWSNarratorNVDAOrcaTalkBackVoiceOver (iOS)VoiceOver (macOS)
ChromeEdgeFirefoxEdgeChromeEdgeFirefoxFirefoxChromeSafariSafari
MUST convey its rolesupportedsupportedsupportedsupportedsupportedsupportedsupportedsupportednonenonesupported
MUST convey the name of the dialogsupportedsupportedsupportedsupportedsupportedsupportedsupportedsupportednonenonesupported
MUST convey the boundaries of the dialogsupportedsupportedsupportednonesupportedsupportedsupportednonenonepartialsupported
MUST NOT automatically switch away from reading modesupportedsupportedsupportedsupportedsupportedsupportedsupportedsupportedsupportedsupportedsupported

Expectation: convey its role

Rationale:

Users must be made aware of the dialog context.

Strength of this expectation for different types of assistive technologies:

  • Screen Readers: MUST
  • Voice Control: NA

Examples:

  • A screen reader might announce an element as something like "<name>, <role>"
  • A screen reader might imply the role by the presence of certain context roles
  • Voice Control software might let the user say something like "click, <role>".
  • Voice Control software might let the user say something like "show numbers", and interactive roles will be flagged with numbers.
Screen Reader support for 'MUST convey its role'
TestJAWSNarratorNVDAOrcaTalkBackVoiceOver (iOS)VoiceOver (macOS)
ChromeEdgeFirefoxEdgeChromeEdgeFirefoxFirefoxChromeSafariSafari
APG modal dialog examplesupportedsupportedsupportedsupportedsupportedsupportedsupportedsupportednonenonesupported

Expectation: convey the name of the dialog

Rationale:

Users need to know the purpose of the dialog.

Strength of this expectation for different types of assistive technologies:

  • Screen Readers: MUST
  • Voice Control: NA
Screen Reader support for 'MUST convey the name of the dialog'
TestJAWSNarratorNVDAOrcaTalkBackVoiceOver (iOS)VoiceOver (macOS)
ChromeEdgeFirefoxEdgeChromeEdgeFirefoxFirefoxChromeSafariSafari
APG modal dialog examplesupportedsupportedsupportedsupportedsupportedsupportedsupportedsupportednonenonesupported

Expectation: convey the boundaries of the dialog

Rationale:

Users need to know when they enter and exit a dialog.

Strength of this expectation for different types of assistive technologies:

  • Screen Readers: MUST
  • Voice Control: NA

Examples:

  • Screen readers might announce something like "entering dialog" or "leaving dialog".
  • Screen readers might imply the boundary by obscuring outside content when aria-modal=true is also present.
Screen Reader support for 'MUST convey the boundaries of the dialog'
TestJAWSNarratorNVDAOrcaTalkBackVoiceOver (iOS)VoiceOver (macOS)
ChromeEdgeFirefoxEdgeChromeEdgeFirefoxFirefoxChromeSafariSafari
APG modal dialog examplesupportedsupportedsupportednonesupportedsupportedsupportednonenonepartialsupported

Expectation: automatically switch away from reading mode

Strength of this expectation for different types of assistive technologies:

  • Screen Readers: MUST NOT
  • Voice Control: NA
Screen Reader support for 'MUST NOT automatically switch away from reading mode'
TestJAWSNarratorNVDAOrcaTalkBackVoiceOver (iOS)VoiceOver (macOS)
ChromeEdgeFirefoxEdgeChromeEdgeFirefoxFirefoxChromeSafariSafari
ARIA dialog role must use document modesupportedsupportedsupportedsupportedsupportedsupportedsupportedsupportedsupportedsupportedsupported
TestLast update
APG modal dialog example2025-08-15
ARIA dialog role must use document mode2024-12-08

Is something not right?

We use our GitHub repository to manage our issue tracking. Please provide as much information as you can for issues, and please leave the id in the issue title intact.

Create an issue for this feature