ARIA: graphics-document role

Description

The graphics-document role applies to the root element of a graphic whose visual representation, usually in two dimensions, carries semantic meaning. Users are expected primarily to browse this content rather than control an application.

It's typically used for structured, semantically meaningful graphics such as flowcharts, maps, diagrams, and technical drawings.

The graphics-document role is distinguished from similar roles as follows:

Unlike an element with the img role, an element with the graphics-document role may include child elements with semantic meaning, such as links and other interactive widgets.
Compared with other document types, a graphics-document is distinguished by the semantic importance of its visual representation.
Unlike a graphics-object, a graphics-document is self-contained: its meaning does not depend on surrounding content, and it provides the context for interpreting its children.

A graphics-document can contain another graphics-document, such as a bar chart embedded in a map. Each nested document provides its own context for navigation.

When dealing with a single large graphic with discrete regions that can be rearranged without changing its meaning, each region should be separated as a standalone graphics-document. You can group these regions using the figure role.

Associated WAI-ARIA roles, states, and properties

aria-labelledby or aria-label: A graphics-document must have an accessible name. Use aria-labelledby if a visible label is present, otherwise use aria-label. For SVG, a <title> element can also provide the name.

Examples

This flowchart uses HTML elements laid out with CSS. The graphics-document role identifies the diagram as a graphical document because the arrangement of its nodes and arrows conveys the authentication flow. The aria-label attribute supplies its accessible name. Each arrow has a graphics-symbol role and a label describing the connection, so the flow can also be understood without seeing the layout.

If this graphic were implemented using <svg> instead, then no role declaration would be necessary because SVG-AAM defines graphics-document as the default role.

html

<div
  class="flowchart"
  role="graphics-document"
  aria-label="User authentication flowchart">
  <div
    class="node start"
    role="graphics-object"
    aria-label="User login: Enter credentials">
    User login
  </div>
  <div
    class="arrow next"
    role="graphics-symbol"
    aria-label="After entering credentials, check whether they are valid"></div>
  <div
    class="node decision"
    role="graphics-object"
    aria-label="Valid?: Are the credentials valid?">
    <span>Valid?</span>
  </div>
  <div
    class="arrow yes"
    role="graphics-symbol"
    aria-label="Yes: If credentials are valid, grant access">
    <span>Yes</span>
  </div>
  <div class="node grant" role="graphics-object">Grant access</div>
  <div
    class="arrow no"
    role="graphics-symbol"
    aria-label="No: If credentials are invalid, deny access">
    <span>No</span>
  </div>
  <div class="node deny" role="graphics-object">Deny access</div>
</div>

css

.flowchart {
  position: relative;
  width: 500px;
  height: 300px;
  color: black;
  background: white;
  font-size: large;
}

.node {
  position: absolute;
  display: grid;
  place-items: center;
  box-sizing: border-box;
  width: 100px;
  height: 60px;
  border: 1px solid black;
}

.start {
  left: 200px;
  top: 30px;
  background: #3eca39;
}

.decision {
  left: 200px;
  top: 130px;
  border: none;
  background: black;
  clip-path: polygon(50% 0, 100% 50%, 50% 100%, 0 50%);
}

.decision::before {
  content: "";
  position: absolute;
  inset: 1px 2px;
  background: #cac539;
  clip-path: inherit;
}

.decision span {
  position: relative;
}

.grant {
  left: 290px;
  top: 220px;
  background: #86ca39;
}

.deny {
  left: 120px;
  top: 220px;
  color: white;
  background: #ca393e;
}

.arrow {
  position: absolute;
  height: 1.6px;
  background: black;
  transform-origin: left center;
}

.arrow::after {
  content: "";
  position: absolute;
  right: 0;
  top: -2.2px;
  border-top: 3px solid transparent;
  border-bottom: 3px solid transparent;
  border-left: 10px solid black;
}

.next {
  left: 250px;
  top: 90px;
  width: 40px;
  transform: rotate(90deg);
}

.yes {
  left: 280px;
  top: 172px;
  width: 77px;
  transform: rotate(39deg);
}

.no {
  left: 220px;
  top: 172px;
  width: 69px;
  transform: rotate(136deg);
}

.arrow span {
  position: absolute;
  left: 25px;
}

.yes span {
  top: -22px;
  transform: rotate(-39deg);
}

.no span {
  top: 8px;
  transform: rotate(-136deg);
}

Best practices

Do not add an explicit graphics-document role when the element already provides that role through its native semantics, as <svg> does.

For decorative SVG graphics, use aria-hidden="true". For graphics without meaningful internal structure, use the img role with an accessible name. For HTML images, use the native <img> element with an alt attribute.

Specifications

Specification
Unknown specification # graphics-document

Help improve MDN

Learn how to contribute

This page was last modified on Oct 14, 2026 by MDN contributors.

View this page on GitHub • Report a problem with this content