Go to overview: WAI-ARIA techniques with code examples

Using aria-describedby to add a description to a close button

Detlev Fischer, (detlev [dot] fischer [ at ] testkreis [dot] de)

Last update: 25 April 2014

The follwing example uses the aria-describedby attribute on the X button to reference the descriptive paragraph following the line "Other content". It also uses the aria-label attribute on the button (value "Close Window") to provide a more meaningful label (example taken from the Mozilla developer network, Using the aria-describedby attribute).

other content

Closing this window will discard any information entered and return you back to the main page

Results for screen reader tests of aria-describedby to add description to close button

iOS 7.1 (on iPhone 5c), VoiceOver not supported
  • Swiping: Reads first the content of aria-label then element type "Close window - button. Does not read element referenced by aria-describedby
  • Touch-explore: Same behaviour as with swiping
Android 4.4.2 (on Nexus 4), Firefox 28.0.1, TalkBack supported
  • Swiping: Reads first the content of aria-label then the sentence referenced by aria-describedby: "Close window - Closing this window will discard any information entered and return you back to the main page. No output of element type (button).
  • Touch-explore: Same behaviour as with swiping
Android 4.2, Firefox 18, TalkBack (German version) Not supported
  • Ignores aria-describedby, reads "Schaltfläche X".
Win 7, IE9, JAWS 13 supported
  • When tabbing: reads first the content of aria-label then the content of the div referenced by aria-describedby: it reads "Close window button - Closing this window will discard..."
  • Normal reading: Reads aria-label, ignores aria-describedby: "Close window button - other content etc.
Win 7, FF 15, JAWS 13 partial support, buggy
  • When tabbing: Reads aria-labelledby twice after reading aria-label and a help text: "close window button - Use JAWS key plus Alt plus R to read descriptive text - Closing this window will discard... - Closing this window will discard...".
  • Normal reading: "close window button - Use JAWS key plus Alt plus R to read descriptive text"
Win 7, IE9, NVDA supported
  • When tabbing: Reads "Close window button - Closing this window will discard..."
  • Normal reading: aria-labelledby ignored: "button Close window - other content" etc.
Win 7, FF 13, NVDA supported
  • When tabbing: Ignores aria-label but reads aria-describedby: "X button - Closing this window will discard..."
  • Normal reading: Ignores both aria-label and aria-describedby: "button X - other content"
Win XP, FF 15, NVDA supported
  • When tabbing: Reads div referenced by aria-describedby but ignores aria-label: it reads "X button - Closing this window will discard..."
  • Normal reading: Ignores both aria-label and aria-describedby, reads "button X - other content" etc.
Win XP, IE8, NVDA supported
  • When tabbing: reads first the content of aria-label then the content of the div referenced by aria-describedby: it reads "Close window button - Closing this window will discard..."
  • Normal reading: reads "button Close window - other content"
Win XP, IE8, SaToGo supported
  • When tabbing: reads div referenced by aria-describedby but ignores aria-label: it reads "X button - Closing this window will discard...".
  • Normal reading: aria-describedby is ignored, the output is "button X - other content" etc.
Mac OS 10.5.8, VoiceOver ? Still to be checked.