Be Wary of doc-subtitle

In early March, Steve Faulkner shared this nugget for making sub-headings:

On its surface it looks pretty handy. Handy enough that Chris Ferdinandi wrote about it in his July 23 post How to create accessible subtitles. Handy enough that Chris Coyier wrote about it in his August 6 post HTML for Subheadings and Headings.

Neither of these talks about support (first Chris is updating his post) nor where the role comes from (first Chris is updating his post again). So let’s wade into both.


If you really need to convey to screen reader users that your sub-head is a distinct yet related heading, then Steve provided a trick. As a reminder, only screen readers do anything with ARIA. Browsers expose it in the accessibility tree, but no other assistive technology uses it. So this solution is strictly for screen reader users.

The doc-subtitle role comes from the Digital Publishing WAI-ARIA Module 1.0, which has been a recommendation since December 2017 (so it is not a new role).

That spec exists for “long-form” documents, which are essentially ebooks.

This specification is a modular extension of WAI-ARIA designed for the digital publishing industry. The goals of this specification include:

  • Expanding [wai-aria-1.1] to produce structural semantic extensions to accommodate the digital publishing industry.
  • […]

The roles defined in this specification are derived from the EPUB Structural Semantics Vocabulary.

1. Introduction, Digital Publishing WAI-ARIA Module 1.0, W3C Recommendation 14 December 2017

It also has a very specific audience.

  • User agents that process content containing WAI-ARIA and Digital Publishing WAI-ARIA features;
  • Assistive technologies that provide specialized reading experiences to users with disabilities;
  • Authors of digital publications;
  • […]
1.1 Target Audience, Digital Publishing WAI-ARIA Module 1.0, W3C Recommendation 14 December 2017

Some of the other roles defined in the spec are clearly aimed at digital versions of paged media: doc-chapter, doc-pagebreak, doc-pagelist.

This does not mean it is technically invalid or incorrect to use doc-subtitle. However, given its purpose in ebooks, its exposure strictly to screen reader users, its lack of contribution to page semantics, and the potential support issues outside of its intended context, doc-subtitle may not be what you want.

As to whether you should expect screen readers to expose it exactly as you expect when browsing in a web context, I’ll let Léonie comment on that:


Léonie Watson quickly tested the role in March, Steve followed up with his own quick tests the same day and again on August 7.

The doc-subtitle role is exposed as a heading with no level. In ARIA 1.1, a level-less heading defaults to level 2, suggesting what we might hear when we test. Under IAccessible2 (IA2), the xml-roles object attribute exposes doc-subtitle, so a screen reader could differentiate if this came into common use. You can explore the MSAA and IA2 properties in Windows using the Accessibility Viewer (aViewer) from TPG.

In Steve’s demo, he adds aria-roledescription to give readers more insight into what this thing is. While you may recall I have opinions on this attribute, I do make an exception for this case because it genuinely does not exist in HTML.

I made a test page (debug view, embedded below), both with and without aria-roledescription to give some insight into support. The examples for my test page come from the Common Idioms section of the HTML 5.2 document, specifically § 4.13.1. Subheadings, subtitles, alternative titles and taglines.

Skip ahead to the verdict if you want to be spared some of the details.

See the Pen RwaaMgB by Adrian Roselli (@aardrian) on CodePen.

Only the second group has aria-roledescription.

Safari with VoiceOver on macOS 10.15.6 will report every instance of doc-subtitle as a heading level 2, even when nested inside an <h1> (the Ramones example). VoiceOver also ignores all instances of aria-roledescription.

JAWS 20 with Chrome 84 also reports every instance of doc-subtitle as a heading level 2. You can override the announcement with aria-roledescription, but JAWS still treats them as heading level 2 in the headings viewer and if you navigate by either H or 2.

JAWS with IE11 ignores doc-subtitle, except for the Ramones example with aria-roledescription. In the Ramones example JAWS announces the value of aria-roledescription but otherwise does not indicate anything related to headings is there. The nodes with doc-subtitle are not exposed in the headings viewer.

NVDA 2020.2 with Firefox 80 announces each in the first group as a heading, except for the Ramones example (where doc-subtitle is on a <span> inside the <h1>) where it announces as level 1 (this is correct). Where aria-roledescription is used, it announces that value instead, and in the Ramones example it also announces as level 1 (this is still correct).

VoiceOver with Safari on iOS and iPadOS 13.4.1 announces all instances of doc-subtitle as heading level 2, except for the one nested in the Ramones example (it seemingly ignores the doc-subtitle). It also completely ignores all instances of aria-roledescription.

TalkBack with Chrome on Android 10 announces each as a subtitle and can navigate to each of them via heading navigation — except for the Ramones example, where it never finds the nested <span> nor its content. It ignores aria-roledescription completely.

TalkBack with Firefox on Android 10 announces each as a heading (no level) and can navigate to each of them via heading navigation. In the Ramones example if you navigate by heading it reads it twice, once as level 1, once as no level. It ignores aria-roledescription completely.

I did not test VoiceOver on macOS with Firefox or Chrome, Narrator on Windows, Orca on GNOME, or other combinations not listed here. You can do that on your own.


In a web (not epub) context:

Broadly, do not put a doc-subtitle inside an <h#>.

What Is Your Goal?

If your goal is genuinely to provide additional context to screen reader users when they encounter a sub-title:
then doc-subtitle and maybe careful use of aria-roledescription could be useful if your audience is only NVDA or TalkBack with Firefox.
If you have some SEO-driven objective (meaning, if you are arguing for using <h#> because search results):
then take a look at alternativeHeadline at instead (or some other microdata format).
If you just want it to look different:
consider using a class or some other non-structural style hook. Then apply your styles, being careful with display properties that can unintentionally impart meaning owing to browser bugs.
If you are convinced you need something else:
look at § 4.13.1. Subheadings, subtitles, alternative titles and taglines and pull one of those patterns.

Of course, no matter which you choose, test.

Update: 18 August 2020

Steve Faulkner is running an informal poll (go read responses for some useful feedback):

He has opened an issue against JAWS to try to get a better announcement in place: 429: Implement support for role=”doc-subtitle”

No comments? Be the first!

Leave a Comment or Response

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>