# How Mermaid's Accessibility System Generates ARIA Attributes for Screen Reader Compatibility > Mermaid automatically adds ARIA attributes and hidden text to SVGs, making diagrams accessible to screen readers. Discover how this system improves chart compatibility. - Repository: [mermaid-js/mermaid](https://github.com/mermaid-js/mermaid) - Tags: internals - Published: 2026-02-23 --- **Mermaid automatically injects ARIA attributes like `role="img"`, `aria-label`, and `aria-describedby` into every SVG diagram, creating hidden `` and `<desc>` elements that allow screen readers to convey visual flowcharts as semantic text.** The mermaid-js/mermaid repository embeds accessibility support directly into its rendering pipeline. When you define a diagram using Mermaid's text-based syntax, the accessibility system analyzes the structure and automatically generates ARIA attributes that make the resulting SVG comprehensible to assistive technologies. This ensures that screen reader users receive meaningful descriptions of node relationships, flow directions, and diagram purpose without requiring manual HTML markup. ## How the Mermaid Accessibility System Operates The accessibility system follows a multi-stage pipeline that transforms textual diagram definitions into semantically rich SVG output. According to the mermaid-js/mermaid source code, this process involves three core phases: parsing the diagram into an abstract syntax tree (AST), generating textual descriptions, and injecting ARIA attributes into the final SVG. ### Diagram Parsing and AST Generation The process begins in the diagram-specific parser logic, such as [`packages/mermaid/src/diagrams/flowchart/parser.ts`](https://github.com/mermaid-js/mermaid/blob/main/packages/mermaid/src/diagrams/flowchart/parser.ts). Here, the textual definition is converted into an AST that represents nodes, edges, and structural relationships. This AST serves as the foundation for accessibility enrichment, providing the accessibility module with a complete map of the diagram's elements and connections. ### Building Textual Descriptions Before SVG emission, the [`accessibility.ts`](https://github.com/mermaid-js/mermaid/blob/main/accessibility.ts) module (located at [`packages/mermaid/src/diagrams/flowchart/accessibility.ts`](https://github.com/mermaid-js/mermaid/blob/main/packages/mermaid/src/diagrams/flowchart/accessibility.ts)) traverses the AST to construct human-readable descriptions. For a flowchart with four nodes and three edges, the module might generate a summary like "Flowchart with 4 nodes and 3 edges" and a detailed description mapping the flow between specific elements. These strings feed directly into the ARIA attributes that screen readers will announce. ### SVG Injection and ARIA Attributes The final rendering stage occurs in [`packages/mermaid/src/svgRenderer.ts`](https://github.com/mermaid-js/mermaid/blob/main/packages/mermaid/src/svgRenderer.ts), which attaches the generated descriptions to the SVG root element and key sub-elements. The system automatically applies four critical accessibility properties: - **`role="img"`** – Signals to screen readers that the SVG should be treated as a single image entity rather than a collection of unrelated graphics. - **`aria-label`** – Contains a concise summary of the diagram, derived from the `title:` directive or auto-generated from node/edge counts. - **`aria-labelledby`** – References a hidden `<title>` element within the SVG, ensuring compatibility with browsers that prioritize the `<title>` tag over the attribute. - **`aria-describedby`** – Points to a `<desc>` element containing the longer, detailed description of nodes, edges, and flow direction. These attributes work in concert with hidden `<title>` and `<desc>` tags inserted directly into the SVG markup, which remain invisible to sighted users but fully exposed to assistive technology. ## Customizing ARIA Attributes and Descriptions While Mermaid generates baseline accessibility text automatically, diagram authors can override these values to provide context-specific descriptions. The system reads custom accessibility settings from directive blocks and applies them during the enrichment phase. ### Overriding the Title with Directives The `title:` directive in the diagram definition overrides the auto-generated `aria-label`. For example: ```mermaid flowchart TD title My Purchase Approval Flow A[Request] --> B{Manager Approval} B -->|Approved| C[Procurement] ``` In this case, the SVG root receives `aria-label="My Purchase Approval Flow"` instead of a generic node count summary. ### Providing Detailed Descriptions via Init Blocks For longer descriptions, authors use the `%%{init}%%` configuration block processed by [`packages/mermaid/src/diagramAPI.ts`](https://github.com/mermaid-js/mermaid/blob/main/packages/mermaid/src/diagramAPI.ts). This allows specification of custom text for the `aria-describedby` reference: ```mermaid %%{init: {'accessibility': { 'description': 'A flowchart showing purchase approval process with manager review gates.' }}}%% flowchart LR A[Request] --> B{Manager Approval} B -->|Approved| C[Procurement] B -->|Rejected| D[Notify Requester] ``` The resulting SVG contains a `<desc>` element with the custom text, referenced by `aria-describedby`, while the `aria-label` remains auto-generated unless explicitly overridden. ## Summary - Mermaid's accessibility system automatically injects **ARIA attributes** into every SVG diagram during the rendering pipeline. - The process involves parsing diagrams into ASTs via [`parser.ts`](https://github.com/mermaid-js/mermaid/blob/main/parser.ts), generating descriptions in [`accessibility.ts`](https://github.com/mermaid-js/mermaid/blob/main/accessibility.ts), and rendering final output in [`svgRenderer.ts`](https://github.com/mermaid-js/mermaid/blob/main/svgRenderer.ts). - Automatically applied attributes include `role="img"`, `aria-label`, `aria-labelledby`, and `aria-describedby`, paired with hidden `<title>` and `<desc>` elements. - Diagram authors can customize accessibility text using the `title:` directive for labels or `%%{init: {'accessibility': {...}}}%%` blocks for detailed descriptions. - Even without explicit configuration, Mermaid produces meaningful structural summaries based on node counts and edge directions to ensure baseline screen reader compatibility. ## Frequently Asked Questions ### What ARIA attributes does Mermaid automatically generate for diagrams? Mermaid automatically applies `role="img"` to the SVG root, along with `aria-label` for concise summaries and `aria-describedby` pointing to detailed descriptions. It also adds `aria-labelledby` referencing a hidden `<title>` element to maximize browser compatibility with screen readers. ### How can I provide custom accessibility text for a Mermaid diagram? You can override the automatic label by adding a `title:` directive to your diagram definition. For detailed descriptions, use the `%%{init: {'accessibility': { 'description': 'Your text here' }}}%%` configuration block, which [`diagramAPI.ts`](https://github.com/mermaid-js/mermaid/blob/main/diagramAPI.ts) parses to populate the `aria-describedby` reference. ### Does Mermaid generate accessibility descriptions if I don't provide any? Yes. If you provide no accessibility hints, the [`accessibility.ts`](https://github.com/mermaid-js/mermaid/blob/main/accessibility.ts) module analyzes the AST from [`parser.ts`](https://github.com/mermaid-js/mermaid/blob/main/parser.ts) to generate descriptions based on diagram structure, such as "Flowchart with 4 nodes and 3 edges" and textual mappings of node connections. This ensures every diagram has baseline screen reader support. ### Which source files control Mermaid's accessibility system? The core logic resides in [`packages/mermaid/src/diagrams/flowchart/accessibility.ts`](https://github.com/mermaid-js/mermaid/blob/main/packages/mermaid/src/diagrams/flowchart/accessibility.ts) for description generation, [`packages/mermaid/src/svgRenderer.ts`](https://github.com/mermaid-js/mermaid/blob/main/packages/mermaid/src/svgRenderer.ts) for SVG element injection, and [`packages/mermaid/src/diagramAPI.ts`](https://github.com/mermaid-js/mermaid/blob/main/packages/mermaid/src/diagramAPI.ts) for parsing accessibility overrides from init blocks. Diagram-specific parsers like [`packages/mermaid/src/diagrams/flowchart/parser.ts`](https://github.com/mermaid-js/mermaid/blob/main/packages/mermaid/src/diagrams/flowchart/parser.ts) supply the AST data required for structural analysis.