Brief Note on Description List Support

TL;DR: Description list support is generally good (with Safari being the outlier), even if you may not like how it is supported.

This post builds on my 2020 tests when iOS 14 finally added (partial) support for description lists (VoiceOver on iOS 14 Supports Description Lists).

The <dl> has existed since HTML+, or 1993, when it was called definition list. After 30 years, developers still seem confused about how they are exposed. This post means I hopefully don’t have to write lengthy emails, Slack posts, threads, or letters sealed with wax and my signet.

Testing Results

This is not meant to indicate if the browser / screen reader combination is adhering to the specification. Nor your idea of how it should. Instead the table only indicates how the construct is conveyed with qualifiers based on my opinion. I care little if it is consistent from screen reader to screen reader, only that it is consistent within one combination.

The browser and screen reader combinations represent the generally recommended pairings for the platform (which is similar to the most common pairings).

Takeaways

With the qualifiers out of the way, here are the key takeaways:

• Having <div>s as (valid) children to the <dl>s had no effect.
• Having multiple <dd>s following each <dt> did not cause issues.
• Do not use description lists if you feel it is imperative that:
  • screen readers announce a count of all nodes (<dt> and <dd>)
  • users can navigate description lists or items with list commands;
  • screen readers announce “term” and “description” / “definition” on all appropriate parts of the list.
• Do not use roles with description lists if you have Safari (macOS, iOS, iPadOS) users and:
  • the counts must be consistent if mixing roled-up and not;
  • the announcement must be consistent if mixing roled-up and not;
  • navigation must be consistent if mixing roled-up and not;
  • The roles are proposed ARIA 1.3 association list roles.
• Maybe do not use roles with description lists if you have TalkBack users and:
  • the announcement must be consistent if mixing roled-up and not;
• Remember users may not care about any of this, so probably test with them.

Key

I am getting weird in how I style these things, so I made a key:

• Yup: my ideal implementation;
• Sure: this implementation is good enough;
• Wut: conveys the critical bits at least;
• Nope: broken (no or incorrect semantics conveyed).

Testing Results

The crunchy bits, which include a lot of footnotes, some kind of round-up per row, and maybe not enough detail for you (it takes a lot of effort to test all these). A pain to read no matter your device because I refactored it so many times I no longer see a table, just my diminished ego.

Added 4 December: If you find this table confounding (I mean, I do), Ben Myers made a prettier layout that does not suffer from trying to convert from Excel and just being tired.

Updated 7 December: I made the table(s) suck less.

1. Announced as a list with 8 items.
2. Announces each DT and DD with a pause.
3. Arrow key stops at each DT and DD.
4. Only navigates DTs.
5. Announced as a definition list with 4 items.
6. Announces each DT and DD together.
7. Announced as a list with 4 items.
8. Only DTs get announced.
9. Announced as a description list with 8 items.
10. Does not announce list.
11. Each DT and DD is exposed as a text element.
12. Announces as a description list with 4 items.
13. Announces as a description list with 8 items.
14. Announces DD with trailing “definition”.
15. Announces DT with trailing “term”.
16. Announces as list, no count.
17. Announces as description list, no count.
18. Announces DD with trailing “description”.
19. Announces as a single string, no pauses, no roles, no list items.

The Tests

I only put together three tests for six roles and three elements, so the permutations are not thorough. I confirmed that adding <div>s as children of the <dl> did not affect announcement, but I could not be bothered to add more columns to the table saying as much.

You can build on these for your own use. Visit them at Codepen or view the debug version. Each passed checks (as appropriate) by the Nu HTML Checker and survived, as well as automated accessibility testing tools WAVE, Axe, and ARC (dismissing false positives).

I again encourage you to try your own combinations of patterns for testing.

See the Pen Description List Tests by Adrian Roselli (@aardrian) on CodePen.

My testing suite:

• Firefox 107 / NVDA 2022.3.2
• Chrome 107 / JAWS 2023
• Edge 107 / Narrator / Win11 22H2
• Safari 16.1 / VoiceOver / macOS 12.6.1
• Chrome 107 / TalkBack 13 / Android 13
• Safari 16.1 / VoiceOver / iPadOS 16.1

Related

• HTML 5, § 4.4.9 The dl element
• HTML 5, § 4.4.10 The dt element
• HTML 5, § 4.4.11 The dd element
• ARIA 1.1 term role
• ARIA 1.1 definition role
• ARIA 1.3 DRAFT associationlist role
• ARIA 1.3 DRAFT associationlistitemkey role
• ARIA 1.3 DRAFT associationlistitemvalue role
• HTML Accessibility API Mappings 1.0 Working Draft, § 3.4 HTML Element Role Mappings for <dl> (no corresponding role)
• HTML Accessibility API Mappings 1.0 Working Draft, § 3.4 HTML Element Role Mappings for <dt> (term role, same as <dfn>)
• HTML Accessibility API Mappings 1.0 Working Draft, § 3.4 HTML Element Role Mappings for <dd> (definition role)
• Accessibility Support, dl element (description list) (html)
• MDN, <dl>: The Description List element
• NVDA issue, #3858 Definition lists not exposed correctly, February 2014
• JAWS issue, #157 Support for Definition/Description Lists, December 2018
• Jules Ernst, Description list, March 2018

Update: 25 March 2024

Tim White performed some testing with JAWS and VoiceOver and, unlike my post, he included VoiceOver with Chrome. Much briefer tests and therefore likely easier to read. He also posted a video of each test to YouTube, something I could not be arsed to do.