Explanation

The Digital Publishing WAI-ARIA module (DPUB-ARIA) is an extension of the ARIA specification. It provides an additional set of publishing-specific roles for use with the ARIA role attribute.

The publishing roles are intended to improve the usability of publications both by providing AT with additional information about important structures and by ensuring that common publishing markup idioms are accessible.

The roles are not intended as a mechanism for workflow semantics so do not provide the same breadth of coverage as, for example, the EPUB Structural Semantics vocabulary. Care needs to be taken both with the number of roles used and the manner in which they are used, as incorrect use will actually impair the ability of users to accessibly consume a publication.

Note

Although this document identifies all the elements the DPUB-ARIA roles can be used on for completeness, many of the possible elements make no sense to use. The most typical uses are called out in the usage sections.

Roles

doc-abstract

A short summary of the principle ideas, concepts and conclusions of the work, or of a section or excerpt within it.

Examples
<section role="doc-abstract" aria-label="abstract">
   <p>This paper examines the effects of …</p>
   …
</section>
<article aria-labelledby="hd">
   <h2 id="hd">Deoxyribonucleic Acid Self-Replication</h2>
   <p role="doc-abstract">The cause of self-replicating DNA…</p>
   …
</section>
Usage

doc-abstract inherits its semantics from the a section role (i.e., it represents a container of related content, but is not a landmark).

It is typically used on section and div elements when it consists of more than one paragraph, but can be used on a p tag when the abstract is a single paragraph.

List of all elements allowed on
  • a (without an href attribute)
  • abbr
  • address
  • b
  • bdi
  • bdo
  • blockquote
  • br
  • canvas
  • cite
  • code
  • del
  • dfn
  • div
  • em
  • i
  • img (with alt text)
  • ins
  • kbd
  • mark
  • output
  • p
  • pre
  • q
  • rp
  • rt
  • ruby
  • s
  • samp
  • small
  • section
  • span
  • strong
  • sub
  • sup
  • table
  • tbody
  • td
  • tfoot
  • thead
  • th
  • tr
  • time
  • u
  • var
  • wbr

See also the definition of doc-abstract in the DPUB-ARIA module.

doc-acknowledgments

A section or statement that acknowledges significant contributions by persons, organizations, governments and other entities to the realization of the work.

Examples
<section role="doc-acknowledgments" aria-labelledby="ack-hd">
   <h2 id="ack-hd">A Word of Thanks</h2>
   …
</section>
Usage

doc-acknowledgments is a landmark role.

It is typically used on section elements.

List of all elements allowed on
  • a (without an href attribute)
  • abbr
  • address
  • b
  • bdi
  • bdo
  • blockquote
  • br
  • canvas
  • cite
  • code
  • del
  • dfn
  • div
  • em
  • i
  • img (with alt text)
  • ins
  • kbd
  • mark
  • output
  • p
  • pre
  • q
  • rp
  • rt
  • ruby
  • s
  • samp
  • section
  • small
  • span
  • strong
  • sub
  • sup
  • table
  • tbody
  • td
  • tfoot
  • thead
  • th
  • tr
  • time
  • u
  • var
  • wbr

See also the definition of doc-acknowledgments in the DPUB-ARIA module.

doc-afterword

A closing statement from the author or a person of importance, typically providing insight into how the content came to be written, its significance, or related events that have transpired since its timeline.

Examples
<section role="doc-afterword" aria-labelledby="aft-hd">
   <h2 id="aft-hd">Afterword by I.M. Faymus</h2>
   …
</section>
Usage

doc-afterword is a landmark role.

It is typically used on section elements.

List of all elements allowed on
  • a (without an href attribute)
  • abbr
  • address
  • b
  • bdi
  • bdo
  • blockquote
  • br
  • canvas
  • cite
  • code
  • del
  • dfn
  • div
  • em
  • i
  • img (with alt text)
  • ins
  • kbd
  • mark
  • output
  • p
  • pre
  • q
  • rp
  • rt
  • ruby
  • s
  • samp
  • section
  • small
  • span
  • strong
  • sub
  • sup
  • table
  • tbody
  • td
  • tfoot
  • thead
  • th
  • tr
  • time
  • u
  • var
  • wbr

See also the definition of doc-afterword in the DPUB-ARIA module.

doc-appendix

A section of supplemental information located after the primary content that informs the content but is not central to it.

Examples
<section role="doc-appendix" aria-labelledby="appa-hd">
   <h2 id="appa-hd">Appendix A: A Timeline of Celestial Events</h2>
   …
</section>
Usage

doc-appendix is a landmark role.

It is typically used on section elements.

List of all elements allowed on
  • a (without an href attribute)
  • abbr
  • address
  • b
  • bdi
  • bdo
  • blockquote
  • br
  • canvas
  • cite
  • code
  • del
  • dfn
  • div
  • em
  • i
  • img (with alt text)
  • ins
  • kbd
  • mark
  • output
  • p
  • pre
  • q
  • rp
  • rt
  • ruby
  • s
  • samp
  • section
  • small
  • span
  • strong
  • sub
  • sup
  • table
  • tbody
  • td
  • tfoot
  • thead
  • th
  • tr
  • time
  • u
  • var
  • wbr

See also the definition of doc-appendix in the DPUB-ARIA module.

doc-biblioentry

Use of the doc-biblioentry role is not recommended as recent updates to the ARIA specification have resulted in it no longer being compatible with ARIA's core list role requirements (i.e., list must only contain listitem roles).

If a bibliography does not use a list to represent its entries, the core list and listitem roles should be used instead:

<section role="bibliography" aria-labelledby="bib-hd">
   <h2 id="bib-hd">Select Bibliography</h2>
   <div role="list">
      <div role="listitem">Doe, John. Anonymous People through History. …</div>
      …
   </div>
</section>

doc-bibliography

A list of external references cited in the work, which may be to print or digital sources.

Examples
<section role="doc-bibliography" aria-labelledby="bib-hd">
   <h2 id="bib-hd">Works Cited</h2>
   …
</section>
Usage

doc-bibliography is a landmark role.

It is typically used on section elements.

List of all elements allowed on
  • a (without an href attribute)
  • abbr
  • address
  • b
  • bdi
  • bdo
  • blockquote
  • br
  • canvas
  • cite
  • code
  • del
  • dfn
  • div
  • em
  • i
  • img (with alt text)
  • ins
  • kbd
  • mark
  • output
  • p
  • pre
  • q
  • rp
  • rt
  • ruby
  • s
  • samp
  • section
  • small
  • span
  • strong
  • sub
  • sup
  • table
  • tbody
  • td
  • tfoot
  • thead
  • th
  • tr
  • time
  • u
  • var
  • wbr

See also the definition of doc-bibliography in the DPUB-ARIA module.

doc-biblioref

A reference to a bibliography entry.

Examples
<p>
   … "with great power comes great responsibility" [SPIDERMAN]…
</p>
Usage

doc-biblioref inherits its semantics from the a link role.

It is typically used on a elements.

List of all elements allowed on
  • a
  • abbr
  • address
  • b
  • bdi
  • bdo
  • blockquote
  • br
  • canvas
  • cite
  • code
  • del
  • dfn
  • div
  • em
  • i
  • img (with alt text)
  • ins
  • kbd
  • mark
  • output
  • p
  • pre
  • q
  • rp
  • rt
  • ruby
  • s
  • samp
  • small
  • span
  • strong
  • sub
  • sup
  • table
  • tbody
  • td
  • tfoot
  • thead
  • th
  • tr
  • time
  • u
  • var
  • wbr

See also the definition of doc-biblioref in the DPUB-ARIA module.

doc-chapter

A major thematic section of content in a work.

Examples
<section role="doc-chapter" aria-labelledby=c01-hd">
   <h2 id="c01-hd">Chapter 1</h2>
   …
</section>
Usage

doc-chapter is a landmark role.

It is typically used on section elements.

List of all elements allowed on
  • a (without an href attribute)
  • abbr
  • address
  • b
  • bdi
  • bdo
  • blockquote
  • br
  • canvas
  • cite
  • code
  • del
  • dfn
  • div
  • em
  • i
  • img (with alt text)
  • ins
  • kbd
  • mark
  • output
  • p
  • pre
  • q
  • rp
  • rt
  • ruby
  • s
  • samp
  • section
  • small
  • span
  • strong
  • sub
  • sup
  • table
  • tbody
  • td
  • tfoot
  • thead
  • th
  • tr
  • time
  • u
  • var
  • wbr

See also the definition of doc-chapter in the DPUB-ARIA module.

doc-colophon

A short section of production notes particular to the edition (e.g., describing the typeface used), often located at the end of a work.

Examples
<section role="doc-colophon" aria-labelledby="col">
   <h2 id="col">Notes on the Type</h2>
   …
</section>
<p role="doc-colophon" aria-label="Colophon">
   This edition was set on Linotype …
</p>
Usage

doc-colophon inherits its semantics from the a section role (i.e., it represents a container of related content, but is not a landmark).

It is typically used on section and div elements when the colophon consists of more than one paragraph, but can be used on a p tag when the colophon is a single paragraph without a heading.

List of all elements allowed on
  • a (without an href attribute)
  • abbr
  • address
  • b
  • bdi
  • bdo
  • blockquote
  • br
  • canvas
  • cite
  • code
  • del
  • dfn
  • div
  • em
  • i
  • img (with alt text)
  • ins
  • kbd
  • mark
  • output
  • p
  • pre
  • q
  • rp
  • rt
  • ruby
  • s
  • samp
  • section
  • small
  • span
  • strong
  • sub
  • sup
  • table
  • tbody
  • td
  • tfoot
  • thead
  • th
  • tr
  • time
  • u
  • var
  • wbr

See also the definition of doc-colophon in the DPUB-ARIA module.

doc-conclusion

A concluding section or statement that summarizes the work or wraps up the narrative.

Examples
<section role="doc-conclusion" aria-labelledby="concl-hd">
   <h2 id="concl-hd">Final Thoughts</h2>
   …
</section>
Usage

doc-conclusion is a landmark role.

It is typically used on section elements.

List of all elements allowed on
  • a (without an href attribute)
  • abbr
  • address
  • b
  • bdi
  • bdo
  • blockquote
  • br
  • canvas
  • cite
  • code
  • del
  • dfn
  • div
  • em
  • i
  • img (with alt text)
  • ins
  • kbd
  • mark
  • output
  • p
  • pre
  • q
  • rp
  • rt
  • ruby
  • s
  • samp
  • section
  • small
  • span
  • strong
  • sub
  • sup
  • table
  • tbody
  • td
  • tfoot
  • thead
  • th
  • tr
  • time
  • u
  • var
  • wbr

See also the definition of doc-conclusion in the DPUB-ARIA module.

doc-cover

An image that sets the mood or tone for the work and typically includes the title and author.

Examples
<img role="doc-cover" class="cover-img" src="cover.jpg" alt="…"/>
Usage

doc-cover inherits its semantics from the a img role.

It is typically used on img element to identify a single image. It is not appropriate to use it on container elements (e.g., section or div) to group all of the content of a cover page.

List of all elements allowed on
  • a (without an href attribute)
  • abbr
  • address
  • b
  • bdi
  • bdo
  • blockquote
  • br
  • canvas
  • cite
  • code
  • del
  • dfn
  • div
  • em
  • i
  • img (with alt text)
  • ins
  • kbd
  • mark
  • output
  • p
  • pre
  • q
  • rp
  • rt
  • ruby
  • s
  • samp
  • small
  • span
  • strong
  • sub
  • sup
  • table
  • tbody
  • td
  • tfoot
  • thead
  • th
  • tr
  • time
  • u
  • var
  • wbr

See also the definition of doc-cover in the DPUB-ARIA module.

doc-credit

An acknowledgment of the source of integrated content from third-party sources, such as photos. Typically identifies the creator, copyright and any restrictions on reuse.

Examples
<figure>
   <img src="bandersnatch.jpg" alt="The Bandersnatch" />
   <figcaption>
      …
      <p role="doc-credit">Image courtesy of …</p>
   </figcaption>
</figure>
Usage

doc-credit inherits its semantics from the a section role (i.e., it represents a container of related content, but is not a landmark).

It is typically used on p and div elements, depending on whether the credit is a single paragraph or consists of multiple paragraphs. It is not recommended to identify individual credits when they are contained within a section of credits, as the purpose of the section already makes clear the contents.

List of all elements allowed on
  • a (without an href attribute)
  • abbr
  • address
  • b
  • bdi
  • bdo
  • blockquote
  • br
  • canvas
  • cite
  • code
  • del
  • dfn
  • div
  • em
  • i
  • img (with alt text)
  • ins
  • kbd
  • mark
  • output
  • p
  • pre
  • q
  • rp
  • rt
  • ruby
  • s
  • samp
  • section
  • small
  • span
  • strong
  • sub
  • sup
  • table
  • tbody
  • td
  • tfoot
  • thead
  • th
  • tr
  • time
  • u
  • var
  • wbr

See also the definition of doc-credit in the DPUB-ARIA module.

doc-credits

A collection of credits.

Examples
<section role="doc-credits" aria-labelledby="cred-hd">
   <h2 id="cred-hd">Image Permissions</h2>
   <p>Page 18 — Photograph of …</p>
   …
</section>
Usage

doc-credits is a landmark role.

It is typically used on section elements. It is not recommended to identify each individual credit within a section of credits, as users will already be aware of the purpose of the section.

List of all elements allowed on
  • a (without an href attribute)
  • abbr
  • address
  • b
  • bdi
  • bdo
  • blockquote
  • br
  • canvas
  • cite
  • code
  • del
  • dfn
  • div
  • em
  • i
  • img (with alt text)
  • ins
  • kbd
  • mark
  • output
  • p
  • pre
  • q
  • rp
  • rt
  • ruby
  • s
  • samp
  • section
  • small
  • span
  • strong
  • sub
  • sup
  • table
  • tbody
  • td
  • tfoot
  • thead
  • th
  • tr
  • time
  • u
  • var
  • wbr

See also the definition of doc-credits in the DPUB-ARIA module.

doc-dedication

An inscription at the front of the work, typically addressed in tribute to one or more persons close to the author.

Examples
<section role="doc-dedication">
   <p>To all the girls I've loved before …</p>
</section>
Usage

doc-dedication inherits its semantics from the a section role (i.e., it represents a container of related content, but is not a landmark).

It is typically used on p, section and div elements, depending on whether the credit is a single paragraph or consists of multiple paragraphs.

List of all elements allowed on
  • a (without an href attribute)
  • abbr
  • address
  • b
  • bdi
  • bdo
  • blockquote
  • br
  • canvas
  • cite
  • code
  • del
  • dfn
  • div
  • em
  • i
  • img (with alt text)
  • ins
  • kbd
  • mark
  • output
  • p
  • pre
  • q
  • rp
  • rt
  • ruby
  • s
  • samp
  • section
  • small
  • span
  • strong
  • sub
  • sup
  • table
  • tbody
  • td
  • tfoot
  • thead
  • th
  • tr
  • time
  • u
  • var
  • wbr

See also the definition of doc-dedication in the DPUB-ARIA module.

doc-endnote

Use of the doc-endnote role is not recommended as recent updates to the ARIA specification have resulted in it no longer being compatible with ARIA's core list role requirements (i.e., list must only contain listitem roles). A future version of the DPUB-ARIA module is expected to deprecate this role.

If an endnotes section does not use a list to represent its entries, the core list and listitem roles should be used instead:

<section role="endnotes" aria-labelledby="note-hd">
   <h2 id="note-hd">Notes</h2>
   
   <div role="list">
      <p id="n001" role="listitem">1. In the far reaches of space …</p>
      …
   </div>
</section>

doc-endnotes

A collection of notes at the end of a work or a section within it.

Examples
<section role="doc-endnotes" aria-labelledby="note-hd">
   <h2 id="note-hd">Notes</h2>
   
   <section>
      <h3>Chapter 1</h3>
      …
   </section>
   …
</section>
Usage

doc-endnotes is a landmark role.

It is typically used on section elements. The requirement that an element with the role doc-endnotes also have at least one element with the role doc-endnote should be ignored until a new version of the vocabulary is released it that resolves the incompatibility.

List of all elements allowed on
  • a (without an href attribute)
  • abbr
  • address
  • b
  • bdi
  • bdo
  • blockquote
  • br
  • canvas
  • cite
  • code
  • del
  • dfn
  • div
  • em
  • i
  • img (with alt text)
  • ins
  • kbd
  • mark
  • output
  • p
  • pre
  • q
  • rp
  • rt
  • ruby
  • s
  • samp
  • section
  • small
  • span
  • strong
  • sub
  • sup
  • table
  • tbody
  • td
  • tfoot
  • thead
  • th
  • tr
  • time
  • u
  • var
  • wbr

See also the definition of doc-endnotes in the DPUB-ARIA module.

doc-epigraph

A quotation set at the start of the work or a section that establishes the theme or sets the mood.

Examples
<blockquote role="doc-epigraph">
   <p>I always get to where I'm going 
         by walking away from where I have been.</p>
         
   <footer>—Winnie the Pooh</footer>
</blockquote>
Usage

doc-epigraph inherits its semantics from the a section role (i.e., it represents a container of related content, but is not a landmark).

It is typically used on blockquote and section elements.

List of all elements allowed on
  • a (without an href attribute)
  • abbr
  • address
  • b
  • bdi
  • bdo
  • blockquote
  • br
  • canvas
  • cite
  • code
  • del
  • dfn
  • div
  • em
  • i
  • img (with alt text)
  • ins
  • kbd
  • mark
  • output
  • p
  • pre
  • q
  • rp
  • rt
  • ruby
  • s
  • samp
  • small
  • span
  • strong
  • sub
  • sup
  • table
  • tbody
  • td
  • tfoot
  • thead
  • th
  • tr
  • time
  • u
  • var
  • wbr

See also the definition of doc-epigraph in the DPUB-ARIA module.

doc-epilogue

A concluding section of narrative that wraps up or comments on the actions and events of the work, typically from a future perspective.

Examples
<section role="doc-epilogue" aria-label="Epilogue">
   <p>Long after the events of the story concluded, I still found myself wondering …</p>
   …
</section>
<section role="doc-epilogue" aria-labelledby="epi-hd">
   <h2 id="epi-hd">Ten Years Later</h2>
   …
</section>
Usage

doc-epilogue is a landmark role.

It is typically used on section elements.

List of all elements allowed on
  • a (without an href attribute)
  • abbr
  • address
  • b
  • bdi
  • bdo
  • blockquote
  • br
  • canvas
  • cite
  • code
  • del
  • dfn
  • div
  • em
  • i
  • img (with alt text)
  • ins
  • kbd
  • mark
  • output
  • p
  • pre
  • q
  • rp
  • rt
  • ruby
  • s
  • samp
  • section
  • small
  • span
  • strong
  • sub
  • sup
  • table
  • tbody
  • td
  • tfoot
  • thead
  • th
  • tr
  • time
  • u
  • var
  • wbr

See also the definition of doc-epilogue in the DPUB-ARIA module.

doc-errata

A set of corrections discovered after initial publication of the work, sometimes referred to as corrigenda.

Examples
<section role="doc-errata" aria-labelledby="corr-hd">
   <h2 id="corr-hd">Errata for the Fifth Edition</h2>
   …
</section>
Usage

doc-errata is a landmark role.

It is typically used on section elements. Do not use the role on list elements. List(s) of errata occurs inside the element carrying the doc-errata role.

List of all elements allowed on
  • a (without an href attribute)
  • abbr
  • address
  • b
  • bdi
  • bdo
  • blockquote
  • br
  • canvas
  • cite
  • code
  • del
  • dfn
  • div
  • em
  • i
  • img (with alt text)
  • ins
  • kbd
  • mark
  • output
  • p
  • pre
  • q
  • rp
  • rt
  • ruby
  • s
  • samp
  • section
  • small
  • span
  • strong
  • sub
  • sup
  • table
  • tbody
  • td
  • tfoot
  • thead
  • th
  • tr
  • time
  • u
  • var
  • wbr

See also the definition of doc-errata in the DPUB-ARIA module.

doc-example

An illustratration of a key concept of the work, such as a code listing, case study or problem.

Examples
<figure role="doc-example" aria-labelledby="ex01-hd">
   <figcaption>
      <p class="hd" id="ex01-hd">Example 1 — Glucose Molecule</p>
      
      <details>
         <summary>Description</summary>
         <p>The 6 carbon atoms are ordered …</p>
       </details>
   </figcaption>
   
   <img src="glucose.jpeg" alt="C6H1206" aria-describedby="glucose-desc"/>
</figure>
<p>The most basic hello world example:</p>
   <pre role="doc-example">print "Hello World!";</pre>
<p>can be executed after compiling …</p>
Usage

doc-example inherits its semantics from the a section role (i.e., it represents a container of related content, but is not a landmark).

It is typically used on figure and pre elements.

List of all elements allowed on
  • a (without an href attribute)
  • abbr
  • address
  • aside
  • b
  • bdi
  • bdo
  • blockquote
  • br
  • canvas
  • cite
  • code
  • del
  • dfn
  • div
  • em
  • i
  • img (with alt text)
  • ins
  • kbd
  • mark
  • output
  • p
  • pre
  • q
  • rp
  • rt
  • ruby
  • s
  • samp
  • section
  • small
  • span
  • strong
  • sub
  • sup
  • table
  • tbody
  • td
  • tfoot
  • thead
  • th
  • tr
  • time
  • u
  • var
  • wbr

See also the definition of doc-example in the DPUB-ARIA module.

doc-footnote

Ancillary information, such as a citation or commentary, that provides additional context to a referenced passage of text.

Examples
<aside role="doc-footnote">
   …
</aside>
Usage

doc-footnote inherits its semantics from the a section role (i.e., it represents a container of related content, but is not a landmark).

It is typically used on aside elements.

List of all elements allowed on
  • a (without an href attribute)
  • abbr
  • address
  • aside
  • b
  • bdi
  • bdo
  • blockquote
  • br
  • canvas
  • cite
  • code
  • del
  • dfn
  • div
  • em
  • footer
  • header
  • i
  • img (with alt text)
  • ins
  • kbd
  • mark
  • output
  • p
  • pre
  • q
  • rp
  • rt
  • ruby
  • s
  • samp
  • small
  • span
  • strong
  • sub
  • sup
  • table
  • tbody
  • td
  • tfoot
  • thead
  • th
  • tr
  • time
  • u
  • var
  • wbr

See also the definition of doc-footnote in the DPUB-ARIA module.

doc-foreword

An introductory section that precedes the work, typically not written by the author of the work.

Examples
<section role="doc-foreword" aria-labelledby="hd01">
   <h2 id="hd01">Foreword by Francis Bacon</h2>
   …
</section>
Usage

doc-foreword is a landmark role.

It is typically used on section elements.

List of all elements allowed on
  • a (without an href attribute)
  • abbr
  • address
  • b
  • bdi
  • bdo
  • blockquote
  • br
  • canvas
  • cite
  • code
  • del
  • dfn
  • div
  • em
  • i
  • img (with alt text)
  • ins
  • kbd
  • mark
  • output
  • p
  • pre
  • q
  • rp
  • rt
  • ruby
  • s
  • samp
  • section
  • small
  • span
  • strong
  • sub
  • sup
  • table
  • tbody
  • td
  • tfoot
  • thead
  • th
  • tr
  • time
  • u
  • var
  • wbr

See also the definition of doc-foreword in the DPUB-ARIA module.

doc-glossary

A brief dictionary of new, uncommon or specialized terms used in the content.

Examples
<section role="doc-glossary" aria-labelledby="gloss-hd">
   <h2 id="gloss-hd">Terms and Definitions</h2>
   <dl>
      <dt><dfn>newfangled</dfn></dt>
      <dd>an improved version that does not …</dd>
      …
   </dl>
</section>
<aside role="doc-glossary" aria-labelledby="term-hd">
   <h2 id="term-hd">Critical Terms for Chapter 1</h2>
   …
</aside>
Usage

doc-glossary is a landmark role.

It is typically used on section elements.

List of all elements allowed on
  • a (without an href attribute)
  • abbr
  • address
  • b
  • bdi
  • bdo
  • blockquote
  • br
  • canvas
  • cite
  • code
  • del
  • dfn
  • div
  • em
  • i
  • img (with alt text)
  • ins
  • kbd
  • mark
  • output
  • p
  • pre
  • q
  • rp
  • rt
  • ruby
  • s
  • samp
  • section
  • small
  • span
  • strong
  • sub
  • sup
  • table
  • tbody
  • td
  • tfoot
  • thead
  • th
  • tr
  • time
  • u
  • var
  • wbr

See also the definition of doc-glossary in the DPUB-ARIA module.

doc-glossref

A reference to a glossary definition.

Examples
<p>
   In monetary policy, short term interest rates allow 
   central banks to …
</p>
Usage

doc-glossref inherits its semantics from the a link role.

It is typically used on a elements.

List of all elements allowed on
  • a
  • abbr
  • address
  • b
  • bdi
  • bdo
  • blockquote
  • br
  • canvas
  • cite
  • code
  • del
  • dfn
  • div
  • em
  • i
  • img (with alt text)
  • ins
  • kbd
  • mark
  • output
  • p
  • pre
  • q
  • rp
  • rt
  • ruby
  • s
  • samp
  • small
  • span
  • strong
  • sub
  • sup
  • table
  • tbody
  • td
  • tfoot
  • thead
  • th
  • tr
  • time
  • u
  • var
  • wbr

See also the definition of doc-glossref in the DPUB-ARIA module.

doc-index

A navigational aid that provides a detailed list of links to key subjects, names and other important topics covered in the work.

Examples
<nav role="doc-index" aria-labelledby="idx-hd">
   <h2 id="idx-hd">Name Index</h2>
   …
</nav>
Usage

doc-index is a landmark role.

It is typically used on nav and section elements.

List of all elements allowed on
  • a (without an href attribute)
  • abbr
  • address
  • b
  • bdi
  • bdo
  • blockquote
  • br
  • canvas
  • cite
  • code
  • del
  • dfn
  • div
  • em
  • i
  • img (with alt text)
  • ins
  • kbd
  • mark
  • nav
  • output
  • p
  • pre
  • q
  • rp
  • rt
  • ruby
  • s
  • samp
  • section
  • small
  • span
  • strong
  • sub
  • sup
  • table
  • tbody
  • td
  • tfoot
  • thead
  • th
  • tr
  • time
  • u
  • var
  • wbr

See also the definition of doc-index in the DPUB-ARIA module.

doc-introduction

A preliminary section that typically introduces the scope or nature of the work.

Examples
<section role="doc-introduction" aria-label="Introduction">
   <p>Recent theory about the nature of gravity …</p>
   …
</section>
Usage

doc-introduction is a landmark role.

It is typically used on section elements.

List of all elements allowed on
  • a (without an href attribute)
  • abbr
  • address
  • b
  • bdi
  • bdo
  • blockquote
  • br
  • canvas
  • cite
  • code
  • del
  • dfn
  • div
  • em
  • i
  • img (with alt text)
  • ins
  • kbd
  • mark
  • output
  • p
  • pre
  • q
  • rp
  • rt
  • ruby
  • s
  • samp
  • section
  • small
  • span
  • strong
  • sub
  • sup
  • table
  • tbody
  • td
  • tfoot
  • thead
  • th
  • tr
  • time
  • u
  • var
  • wbr

See also the definition of doc-introduction in the DPUB-ARIA module.

doc-noteref

A reference to a footnote or endnote, typically appearing as a superscripted number or symbol in the main body of text.

Examples
<p> … as exhibited in the work of Prof.
   Farnsworth.<a role="doc-noteref" href="#fn-01" class="sup">1</a>
</p>
<aside id="fn-01" role="doc-footnote">
   <p>1. The Fing-Longer is one of the …</p>
</aside>
Usage

doc-noteref inherits its semantics from the a link role.

It is typically used on a elements.

List of all elements allowed on
  • a
  • abbr
  • address
  • b
  • bdi
  • bdo
  • blockquote
  • br
  • canvas
  • cite
  • code
  • del
  • dfn
  • div
  • em
  • i
  • img (with alt text)
  • ins
  • kbd
  • mark
  • output
  • p
  • pre
  • q
  • rp
  • rt
  • ruby
  • s
  • samp
  • small
  • span
  • strong
  • sub
  • sup
  • table
  • tbody
  • td
  • tfoot
  • thead
  • th
  • tr
  • time
  • u
  • var
  • wbr

See also the definition of doc-noteref in the DPUB-ARIA module.

doc-notice

Notifies the user of consequences that might arise from an action or event. Examples include warnings, cautions and dangers.

Examples
<div role="doc-notice" class="warning" aria-label="warning">
   <p>Exercise caution when mixing …</p>
</div>
<div role="doc-notice" class="danger" aria-labelledby="alert01">
   <img id="alert01" src="warn.jpg" alt="Warning"/>
   <p>Serious bodily injury may result …</p>
</div>
Usage

doc-notice inherits its semantics from the a note role.

It is typically used on div elements. The role is particularly useful when colour is used as the primary indicator of importance (e.g., warnings might have a yellow border and dangers red instead of explicit labels).

List of all elements allowed on
  • a (without an href attribute)
  • abbr
  • address
  • b
  • bdi
  • bdo
  • blockquote
  • br
  • canvas
  • cite
  • code
  • del
  • dfn
  • div
  • em
  • i
  • img (with alt text)
  • ins
  • kbd
  • mark
  • output
  • p
  • pre
  • q
  • rp
  • rt
  • ruby
  • s
  • samp
  • section
  • small
  • span
  • strong
  • sub
  • sup
  • table
  • tbody
  • td
  • tfoot
  • thead
  • th
  • tr
  • time
  • u
  • var
  • wbr

See also the definition of doc-notice in the DPUB-ARIA module.

doc-pagebreak

A separator denoting the position before which a break occurs between two contiguous pages in a statically paginated version of the content.

Examples
<hr id="pg004" role="doc-pagebreak" aria-label="4">
<div id="pg032" role="doc-pagebreak">32</div>
<p> … the <span id="pg159" role="doc-pagebreak" aria-label="159"/>
   interregnum period was characterized by …</p>
Usage

doc-pagebreak inherits its semantics from the a separator role.

It is typically used on hr, div and span elements. The page number must be clearly expressed either in an aria-label attribute or as the text content of the element. While using a prefix like "page" or "pg" is common in the id for the element, do not include such prefixes in the label (i.e., the label should only include a number unless the source also includes a prefix).

List of all elements allowed on
  • a (without an href attribute)
  • abbr
  • address
  • b
  • bdi
  • bdo
  • blockquote
  • br
  • canvas
  • cite
  • code
  • del
  • dfn
  • div
  • em
  • hr
  • i
  • img (with alt text)
  • ins
  • kbd
  • mark
  • output
  • p
  • pre
  • q
  • rp
  • rt
  • ruby
  • s
  • samp
  • small
  • span
  • strong
  • sub
  • sup
  • table
  • tbody
  • td
  • tfoot
  • thead
  • th
  • tr
  • time
  • u
  • var
  • wbr

See also the definition of doc-pagebreak in the DPUB-ARIA module.

doc-pagelist

A navigational aid that provides a list of links to the pagebreaks in the content.

Examples
<nav role="doc-pagelist" aria-labelledby="pg-hd">
   <h2 id="pg-hd">List of Pages</h2>
   <ol>
      <li><a href="#intro.html#pgi">i</a></li>
      <li><a href="#intro.html#pgii">ii</a></li>
      …
      <li><a href="#c01.html#pg001">1</a></li>
      …
      <li><a>298 (omitted)</a></li>
   </ol>
</nav>
Usage

doc-pagelist is a landmark role.

It is typically used on nav elements. Refer to page navigation for more information about authoring page lists.

List of all elements allowed on
  • a (without an href attribute)
  • abbr
  • address
  • b
  • bdi
  • bdo
  • blockquote
  • br
  • canvas
  • cite
  • code
  • del
  • dfn
  • div
  • em
  • i
  • img (with alt text)
  • ins
  • kbd
  • mark
  • nav
  • output
  • p
  • pre
  • q
  • rp
  • rt
  • ruby
  • s
  • samp
  • section
  • small
  • span
  • strong
  • sub
  • sup
  • table
  • tbody
  • td
  • tfoot
  • thead
  • th
  • tr
  • time
  • u
  • var
  • wbr

See also the definition of doc-pagelist in the DPUB-ARIA module.

doc-part

A major structural division in a work that contains a set of related sections dealing with a particular subject, narrative arc or similar encapsulated theme.

Examples
<section role="doc-part" aria-labelledby="p1-hd">
   <h2 id="p1-hd">I — The Visitor</h2>
   …
</section>
Usage

doc-part is a landmark role.

It is typically used on section elements.

List of all elements allowed on
  • a (without an href attribute)
  • abbr
  • address
  • b
  • bdi
  • bdo
  • blockquote
  • br
  • canvas
  • cite
  • code
  • del
  • dfn
  • div
  • em
  • i
  • img (with alt text)
  • ins
  • kbd
  • mark
  • output
  • p
  • pre
  • q
  • rp
  • rt
  • ruby
  • s
  • samp
  • section
  • small
  • span
  • strong
  • sub
  • sup
  • table
  • tbody
  • td
  • tfoot
  • thead
  • th
  • tr
  • time
  • u
  • var
  • wbr

See also the definition of doc-part in the DPUB-ARIA module.

doc-preface

An introductory section that precedes the work, typically written by the author of the work.

Examples
<section role="doc-preface" aria-labelledby="pref-hd">
   <h2 id="pref-hd">Prefatory Note from the Author</h2>s
   <p>When I first put pen to paper …</p>
   …
</section>
Usage

doc-preface is a landmark role.

It is typically used on section elements.

List of all elements allowed on
  • a (without an href attribute)
  • abbr
  • address
  • b
  • bdi
  • bdo
  • blockquote
  • br
  • canvas
  • cite
  • code
  • del
  • dfn
  • div
  • em
  • i
  • img (with alt text)
  • ins
  • kbd
  • mark
  • output
  • p
  • pre
  • q
  • rp
  • rt
  • ruby
  • s
  • samp
  • section
  • small
  • span
  • strong
  • sub
  • sup
  • table
  • tbody
  • td
  • tfoot
  • thead
  • th
  • tr
  • time
  • u
  • var
  • wbr

See also the definition of doc-preface in the DPUB-ARIA module.

doc-prologue

An introductory section that sets the background to a work, typically part of the narrative.

Examples
<section role="doc-prologue" aria-labelledby="prol-hd">
   <h2 id="prol-hd">Prologue</h2>
   …
</section>
Usage

doc-prologue is a landmark role.

It is typically used on section elements.

List of all elements allowed on
  • a (without an href attribute)
  • abbr
  • address
  • b
  • bdi
  • bdo
  • blockquote
  • br
  • canvas
  • cite
  • code
  • del
  • dfn
  • div
  • em
  • i
  • img (with alt text)
  • ins
  • kbd
  • mark
  • output
  • p
  • pre
  • q
  • rp
  • rt
  • ruby
  • s
  • samp
  • section
  • small
  • span
  • strong
  • sub
  • sup
  • table
  • tbody
  • td
  • tfoot
  • thead
  • th
  • tr
  • time
  • u
  • var
  • wbr

See also the definition of doc-prologue in the DPUB-ARIA module.

doc-pullquote

A distinctively placed or highlighted quotation from the current content designed to draw attention to a topic or highlight a key point.

Examples
<p>With a deafening crack, 
   <span role="doc-pullquote presentation" id="pq01">a
   cornice broke free high above, unleashing a massive 
   avalanche</span>. … </p>
<blockquote role="doc-pullquote presentation" aria-hidden="true">
   there are few things as important as toast
</blockquote>
Usage

doc-pullquote inherits its semantics from the a none role (i.e., it is presentational).

The role is typically used on span elements when the pullquote is tagged within the content of the publication (i.e., the text will be extracted and formatted later by script to make the presentational pullquote).

It is typically used on blockquote, aside and div elements when the quote is duplicated in a separate element. The addition of an aria-hidden attribute in these cases prevents the content from being read again to users of assistive technologies. A future version of ARIA is expected to introduce a new role for repeated content such as pullquotes that will allow them to be ignored by default but still be accessed by users interested in skimming the quotes.

Note: the ARIA 1.1 specification currently advises adding the backup role of presentation until support for none becomes more prevalent. As doc-pullquote inherits from none, the same advice applies for this role.

List of all elements allowed on
  • a (without an href attribute)
  • abbr
  • address
  • aside
  • b
  • bdi
  • bdo
  • blockquote
  • br
  • canvas
  • cite
  • code
  • del
  • dfn
  • div
  • em
  • i
  • img (with alt text)
  • ins
  • kbd
  • mark
  • output
  • p
  • pre
  • q
  • rp
  • rt
  • ruby
  • s
  • samp
  • section
  • small
  • span
  • strong
  • sub
  • sup
  • table
  • tbody
  • td
  • tfoot
  • thead
  • th
  • tr
  • time
  • u
  • var
  • wbr

See also the definition of doc-pullquote in the DPUB-ARIA module.

doc-qna

A section of content structured as a series of questions and answers, such as an interview or list of frequently asked questions.

Examples
<section role="doc-qna" aria-labelledby="qna-hd">
   <h2 id="qna-hd">Interview with the Author</h2>
   <dl>
   	<dt>What … is your favourite colour?</dt>
   	<dd>Blue. I mean yel—auuuugh!</dd>
   </dl>
</section>
Usage

doc-qna inherits its semantics from the a section role (i.e., it represents a container of related content, but is not a landmark).

It is typically used on section and div elements. The role can also be used directly on a dl element as dt and dd elements are not considered list items by default.

List of all elements allowed on
  • a (without an href attribute)
  • abbr
  • address
  • b
  • bdi
  • bdo
  • blockquote
  • br
  • canvas
  • cite
  • code
  • del
  • dfn
  • div
  • em
  • i
  • img (with alt text)
  • ins
  • kbd
  • mark
  • output
  • p
  • pre
  • q
  • rp
  • rt
  • ruby
  • s
  • samp
  • section
  • small
  • span
  • strong
  • sub
  • sup
  • table
  • tbody
  • td
  • tfoot
  • thead
  • th
  • tr
  • time
  • u
  • var
  • wbr

See also the definition of doc-qna in the DPUB-ARIA module.

doc-subtitle

An explanatory or alternate title for the work, or a section or component within it.

Examples
<header>
   <h2>Section 1 — Applied Metaphysics</h2>
   <p role="doc-subtitle">Who makes up this stuff?</p>
   …
</header>
Usage

doc-subtitle inherits its semantics from the a sectionhead role.

It is typically used on p and div elements. For more information on authoring subtitles, see the section Subheadings, subtitles, alternative titles and taglines in the HTML 5.1 specification.

List of all elements allowed on
  • a (without an href attribute)
  • abbr
  • address
  • b
  • bdi
  • bdo
  • blockquote
  • br
  • canvas
  • cite
  • code
  • del
  • dfn
  • div
  • em
  • h1-h6
  • i
  • img (with alt text)
  • ins
  • kbd
  • mark
  • output
  • p
  • pre
  • q
  • rp
  • rt
  • ruby
  • s
  • samp
  • small
  • span
  • strong
  • sub
  • sup
  • table
  • tbody
  • td
  • tfoot
  • thead
  • th
  • tr
  • time
  • u
  • var
  • wbr

See also the definition of doc-subtitle in the DPUB-ARIA module.

doc-tip

Helpful information that clarifies some aspect of the content or assists in its comprehension.

Examples
<div role="doc-tip" class="tip">
   Counting on your fingers is an easy path to success!
</div>
Usage

doc-tip inherits its semantics from the a note role.

It is typically used on div and p elements.

List of all elements allowed on
  • a (without an href attribute)
  • abbr
  • address
  • b
  • bdi
  • bdo
  • blockquote
  • br
  • canvas
  • cite
  • code
  • del
  • dfn
  • div
  • em
  • i
  • img (with alt text)
  • ins
  • kbd
  • mark
  • output
  • p
  • pre
  • q
  • rp
  • rt
  • ruby
  • s
  • samp
  • small
  • span
  • strong
  • sub
  • sup
  • table
  • tbody
  • td
  • tfoot
  • thead
  • th
  • tr
  • time
  • u
  • var
  • wbr

See also the definition of doc-tip in the DPUB-ARIA module.

doc-toc

A navigational aid that provides an ordered list of links to the major sectional headings in the content. A table of contents may cover an entire work, or only a smaller section of it.

Examples
<nav role="doc-toc">
   <h2 id="hd05">Contents</h2>
   <ol>
      <li><a href="chapter01.html">Chapter 1</a></li>
      …
   </ol>
</nav>
Usage

doc-toc is a landmark role.

It is typically used on nav elements.

List of all elements allowed on
  • a (without an href attribute)
  • abbr
  • address
  • b
  • bdi
  • bdo
  • blockquote
  • br
  • canvas
  • cite
  • code
  • del
  • dfn
  • div
  • em
  • i
  • img (with alt text)
  • ins
  • kbd
  • mark
  • nav
  • output
  • p
  • pre
  • q
  • rp
  • rt
  • ruby
  • s
  • samp
  • section
  • small
  • span
  • strong
  • sub
  • sup
  • table
  • tbody
  • td
  • tfoot
  • thead
  • th
  • tr
  • time
  • u
  • var
  • wbr

See also the definition of doc-toc in the DPUB-ARIA module.

Frequently Asked Questions

What are implicit roles and why do they matter?

Many HTML elements have default accessibility semantics so don't require a an explicit role. The nav element, for example, has the implicit role navigation, as you might expect. Similarly, the aside element has the implicit role complementary. For the complete list of elements and their implicit roles, please see the ARIA in HTML document.

A feature of these implicit roles is that if an assigned role is not recognized, AT are expected to ignore the unknown role and default to the implicit. This ensures that AT can still make sense of the document when encountering, for example, new roles they are not aware of.

To avoid problems with AT not recognizing the DPUB ARIA roles, it is recommended that when an element has an implicit role you ensure that the role you are using has the same ancestor role (e.g., use navigation roles with the nav element).

This issue will diminish as support for the module gains traction now that is a formal specification. It also is imperfect, as there have been reports that implicit roles are not always recognized.

When should I include fallback roles?

When an HTML element does not have an implicit role (e.g., span and div), it is recommended to include a fallback role from the core ARIA specification for whichever role you are using from the DPUB ARIA module. This ensures that even if the DPUB semantic is not yet understood by the AT, it will still understand the purpose of the role.

The role attribute accepts multiple roles separated by spaces, so the ARIA fallback role can be added after the DPUB ARIA role.

The following example shows how the listitem role can be used as a fallback for the DPUB ARIA doc-endnote role so that it is still recognized as a list item.

<div role="doc-endnote listitem">

The order of roles is important, so do no add the ARIA role before the DPUB role or the DPUB role will never be recognized.

Similar to the issue of matching implied semantics, the need for fallback semantics will also diminish with time. The use of fallback semantics is also known to be imperfect, as the fallbacks are not recognized in all cases.

Why shouldn't every section of a publication be a landmark?

Users already have access to the table of contents, which is a much more effective tool for understanding and navigating the structure of a publication. Landmarks are intended to provide quick access to the key sections a user might want to reach.

Landmarks are also an unstructured list of links, so setting every section as a landmark actually makes it harder for users to understand the structure. Making every section a landmark also unnecessarily proliferates the total number of landmarks in a page, which in turn reduces the usefulness of the list (i.e., being able to quickly locate a key section).

Why isn't there a role for every semantic in the EPUB Structural Semantic vocabulary?

The EPUB Structural Semantic vocabulary was designed primarily to provide semantics for publishers' internal workflows. It was hoped at the time that the attribute would be able to serve a dual purpose of providing accessibility mappings for useful roles, but this hope never materialized into a workable solution. Assistive technologies are not aware of the epub:type attribute and there is no interest in trying to reconcile it with the existing ARIA solution.

The result is that the EPUB vocabulary contains far more semantics than will ever be necessary to improve the actual usability of publications. Implementing all of the semantics in a publication would likely just overload users with unnecessary information and make it harder for them to effectively read the publication (i.e., it would create a lot of semantic noise while reading).

References