EPUB Type to ARIA Role Authoring Guide

22 November 2019

Document history


It is important to understand the differences between the epub:type attribute and the ARIA role attribute to ensure that they are properly applied for their intended purposes and audiences.

Arguably the biggest difference is in their primary applications. The epub:type attribute has evolved to facilitate reading system behaviors and to aid publisher workflows. Although it could be used to expose information to assistive technologies (AT), in practice it is not. The primary purpose of the role attribute, on the other hand, is to expose information to AT. Although it could be used to facilitate user agent behaviors, in practice it is not.

The result of these differences is that the application of epub:type semantics is largely harmless, but misapplication of ARIA roles can have negative impacts on the reading experience, from over-announcement of information to broken HTML rendering for AT users.

This guide is not intended as a comprehensive overview of ARIA roles. It only addresses key authoring differences to be aware of when using one or both attributes in EPUB Content Documents.


1. Use Roles on Allowed Elements

ARIA roles are more restricted in where they can be used than EPUB's structural semantics. Although there are a number of elements that accept any role, care needs to be taken to ensure that roles are only used where they will make sense to users of assistive technologies.

The following mapping table identifies the elements that each DPUB-ARIA role can be used with.

Role Mapping Table

The following table maps the semantics from the EPUB Structural Semantics Vocabulary to the corresponding roles in ARIA and the DPUB-ARIA module.

As the use of the epub:type attribute is much more liberal than the ARIA role attribute, not every semantic can be used on every HTML element, even if it has a mapping. Specific elements that roles can be used on are identified in the last column of the table. In addition, refer to the note at the end of the table for the list of elements that accept any role value.

See also the ARIA in HTML document for more information about the correct use of ARIA roles, states and properties.

EPUB Structural Semantics Vocabulary Manifest Properties Digital Publishing WAI-ARIA Module 1.0 ARIA 1.1 Elements Allowed On*
abstract [DRAFT] doc-abstract section
acknowledgments doc-acknowledgments section
afterword doc-afterword section
answer [DRAFT] No Role
answers [DRAFT] No Role
appendix doc-appendix section
assessment No Role
assessments [DRAFT] No Role
backmatter No Role
balloon No Role
biblioentry doc-biblioentry li
bibliography doc-bibliography section
biblioref [DRAFT] doc-biblioref a
bodymatter No Role
bridgehead No Role
case-study [DRAFT] No Role
chapter doc-chapter section
colophon doc-colophon section
concluding-sentence No Role
conclusion doc-conclusion section
contributors No Role
copyright-page No Role
cover No Role
cover-image doc-cover img
covertitle No Role
credit [DRAFT] doc-credit section
credits [DRAFT] doc-credits section
dedication doc-dedication section
division No Role
endnote doc-endnote li
endnotes doc-endnotes section
epigraph doc-epigraph
epilogue doc-epilogue section
errata doc-errata section
No Equivalent doc-example
  • aside
  • section
feedback [DRAFT] No Role
figure figure
fill-in-the-blank-problem [DRAFT] No Role
footnote doc-footnote
  • aside
  • footer
  • header
footnotes No Role
foreword doc-foreword section
frontmatter No Role
fulltitle No Role
general-problem [DRAFT] No Role
glossary doc-glossary section
glossterm term
glossdef definition
glossref [DRAFT] doc-glossref a
halftitle No Role
halftitlepage No Role
imprint No Role
imprimatur No Role
index doc-index
  • nav
  • section
index-headnotes No Role
index-legend No Role
index-group No Role
index-entry-list No Role
index-entry No Role
index-term No Role
index-editor-note No Role
index-locator No Role
index-locator-list No Role
index-locator-range No Role
index-xref-preferred No Role
index-xref-related No Role
index-term-category No Role
index-term-categories No Role
introduction doc-introduction section
keyword No Role
keywords [DRAFT] No Role
label [DRAFT] No Role
landmarks directory
  • ol
  • ul
learning-objective No Role
learning-objectives [DRAFT] No Role
learning-outcome [DRAFT] No Role
learning-outcomes [DRAFT] No Role
learning-resource No Role
learning-resources [DRAFT] No Role
learning-standard [DRAFT] No Role
learning-standards [DRAFT] No Role
list list
list-item listitem
loa No Role
loi No Role
lot No Role
lov No Role
match-problem [DRAFT] No Role
multiple-choice-problem [DRAFT] No Role
noteref doc-noteref a
notice doc-notice section
ordinal [DRAFT] No Role
other-credits No Role
panel No Role
panel-group No Role
pagebreak doc-pagebreak hr
page-list doc-pagelist
  • nav
  • section
part doc-part section
practice [DRAFT] No Role
practices [DRAFT] No Role
preamble No Role
preface doc-preface section
prologue doc-prologue section
pullquote [DRAFT] doc-pullquote
  • aside
  • section
question [DRAFT] No Role
qna doc-qna section
referrer [DRAFT] doc-backlink a
revision-history No Role
seriespage [DRAFT] No Role
sound-area No Role
subchapter No Role
subtitle doc-subtitle h1-h6
table table
table-row row
table-cell cell
text-area No Role
tip doc-tip aside
title No Role
titlepage No Role
toc doc-toc
  • nav
  • section
toc-brief [DRAFT] No Role
topic-sentence No Role
true-false-problem [DRAFT] No Role
volume No Role

2. Do Not Overload Roles

Only use one digital publishing role per attribute:

<section role="doc-chapter">

If you include a second role, it has to be a fallback from ARIA 1.1:

<section role="doc-chapter region">

Note that the fallback must not be one of the ARIA 1.1 Abstract roles. These are never allowed in the role attribute.

Unlike the epub:type attribute, the order of roles is important, and only the first recognized role is applied to an element.

3. Avoid Unnecessary Repetition

Do not reapply a semantic just because your content has been chunked into separate files.

For example, ensure that the doc-part role is only applied to the section that contains the heading for the part. Do not reapply the part role for each chapter that belongs to the part, as it will be announced to users of assistive technologies each time it occurs, causing confusion.

4. Supply Labels

If a landmark role (e.g., doc-chapter, doc-part, doc-index) does not include a label, assistive technologies will not include it in the list of landmarks. A label provides context when deciding which landmark to navigate to (similar capabilities are not available for epub:type).

Use the aria-labelledby attribute to associate a label with the role.

<section role="doc-index" aria-labelledby="idx01">
   <h1 id="idx01">Name Index</h1>

<section role="doc-index" aria-labelledby="idx02">
   <h1 id="idx02">Topical Index</h1>

If a label is not available in the text, one can be supplied in an aria-label attribute.

<section role="chapter" aria-label="chapter 1">
   <p>Once upon a time …</p>

<section role="chapter" aria-label="chapter 2">
   <p>When the forest opened up …</p>

5. Do Not Override the body Element

The epub:type attribute may be used to inflect sectioning semantics on the HTML body element (e.g., to indicate front matter, or to avoid using sectioning elements), but this practice is both invalid and harmful with ARIA roles.

The body element has the implied role document, and no other roles can be defined on the element. Changing the role of the body element can affect the ability to read the content for users of assistive technologies.

6. List Roles are for Lists

Assigning a role to an element overrides its default nature, so use care when applying roles to lists and list items.

Just as HTML ol/ul elements must contain list items, elements assigned a list role must only contain elements assigned a list item role. Similarly, a list item must always be enclosed inside of a list.

For example, the doc-biblioentry role inherits from listitem. As a result, it has to be used inside of a list:

   <li role="doc-biblioentry">…</li>

or else a list role needs to be applied to an element that encloses all the note:

<div role="list">
   <p role="doc-biblioentry">…</li>

7. Cover Role is for Images

Although the doc-cover role from the DPUB-ARIA module seems like it should be the same as the cover semantic from the EPUB Structural Semantics Vocabulary, it is actually related to the cover-image semantic used to identify cover images in the EPUB package document. The role is used to identify an image that represents the cover.

<img role="doc-cover"

This role is not used to identify a section of content containing the cover. Placing the role on a section, for example, informs assistive technologies to treat the element like they would an image. In practical terms, this means that none of its content will be available.

If a section of cover content needs to be identified as a landmark, the aria-label or aria-labelledby attributes can be used with the `section` element:

<section aria-label="Cover: As I Lay Dying. William Faulkner."<

(For `div` elements, the general `region` role is also needed. For more information about how to use roles in content, refer to ARIA in HTML.)