Designing Accessible JSON Formatters for Screen Readers

A JSON formatter becomes hard to use with a screen reader when it only prettifies punctuation. Users hear a long stream of braces, commas, quotes, and indentation instead of the underlying information. The accessible solution is usually not “better syntax highlighting.” It is a better representation of the data, with native HTML, clear labels, predictable keyboard behavior, and a raw JSON view kept as a secondary option.

If you are designing a formatter in 2026, aim for two outcomes at once: let developers inspect the original JSON when they need it, and let screen reader users understand the same payload as headings, terms, definitions, lists, and tables. That approach aligns much better with current WCAG guidance on structure, relationships, status messages, and clear interactive controls.

Design for the task, not the braces

Before choosing a UI pattern, decide what the user is trying to do. “Read this payload” and “copy the exact JSON source” are different jobs, and one view rarely serves both perfectly.

• Understanding a response: Default to semantic HTML that exposes the data model instead of the raw syntax.
• Debugging or copy/paste work: Keep a raw JSON source view available, clearly labeled, with copy or download actions nearby.
• Large payloads: Collapse secondary branches, show counts in toggle labels, and let users jump between major sections.
• Validation workflows: Announce parse errors, line references, and “formatted” states in a predictable status region.

A good accessible formatter usually offers a structured view first and a raw code view second, rather than forcing every user through the same monospaced block.

Map each JSON shape to native HTML

Native HTML gives screen readers the structure they already know how to announce. That is usually more robust than recreating a custom widget with ARIA.

This approach also prevents a common mistake: using tables for arbitrary nested JSON. If the data is not genuinely tabular, a table makes navigation harder instead of easier.

Example: one object, one nested array, one optional branch

<section aria-labelledby="profile-heading">
  <h2 id="profile-heading">Profile</h2>

  <dl>
    <dt>Name</dt>
    <dd>Alice</dd>

    <dt>Role</dt>
    <dd>Editor</dd>
  </dl>

  <details>
    <summary>Permissions, array, 3 items</summary>
    <ul>
      <li>publish</li>
      <li>archive</li>
      <li>review</li>
    </ul>
  </details>
</section>

The important part is not the exact markup combination. It is that every section has a meaningful name, every expandable region tells users what is inside it, and the data is grouped in a way that matches the actual content model.

Use disclosure first, tree only when users truly need a tree

This is where many formatter UIs go wrong. Designers see nested JSON and immediately build a custom tree view. Current WAI-ARIA Authoring Practices are much more cautious: a disclosure pattern is usually better for simply showing and hiding sections, while a full tree widget is appropriate only when users need structured parent/child navigation with dedicated keyboard commands.

• Use <details>/<summary> or a disclosure button when users mostly expand and collapse branches.
• Use a tree only if you are prepared to implement the full keyboard model: arrow keys, Home/End, focus management, expanded state, and clear labeling for each node.
• Do not steal arrow keys for a custom widget unless the widget actually behaves like a tree. Unexpected keyboard capture is a fast way to break screen reader workflows.

In practice, many JSON formatters do not need a tree at all. A disclosure-based outline is simpler to build, easier to test, and more compatible across browser and assistive technology combinations.

Keep raw JSON as a secondary view, not the only view

Sometimes the exact source matters. Developers may need to compare whitespace, inspect quotes, or copy a payload verbatim. Keep that capability, but do not assume the raw code block is enough for accessibility.

• Add a heading or label such as Raw JSON source so users know they are leaving the structured view.
• Put copy, wrap, and download actions in native buttons with specific names like “Copy raw JSON” or “Wrap long lines.” Avoid repeated icon-only controls.
• Treat syntax highlighting as visual enhancement only. Do not rely on color to distinguish keys, strings, or errors, and do not flood the accessibility tree with decorative token wrappers.
• If you show line numbers, hide decorative numbers from assistive technology unless users can actually navigate by them.
• Offer a fast way back to the structured view when a user realizes the code view is too noisy.

Announce formatting, validation, and copy results without being chatty

Modern formatters are interactive. They prettify input, validate syntax, collapse nodes, copy content, and sometimes fetch remote examples. Those state changes should be announced clearly, but only when users need to know about them.

<div role="status" aria-live="polite">
  JSON formatted successfully. 12 top-level properties.
</div>

• Use a polite status region for non-blocking messages such as “formatted,” “copied,” or “3 matches found.”
• Reserve urgent alerts for real problems, such as invalid JSON that prevents formatting.
• Keep focus behavior consistent. If pressing Format updates the same view, focus usually stays on the button or editor. If the action opens a new panel, move focus to a clear heading inside that panel.
• Make toggle labels informative: “address, object, 4 properties” is better than “Expand.”

Keyboard and testing checklist

Accessible JSON formatting is not done when the markup looks correct in DevTools. It is done when the interaction works with real assistive tech.

• Test keyboard-only first: visible focus, logical Tab order, Enter and Space on buttons, and no trapped focus.
• If you built a real tree widget, test the full APG keyboard model, not just expand and collapse.
• Test with at least NVDA plus Firefox, JAWS plus Chrome or Edge, and VoiceOver plus Safari. If your formatter is used on phones or tablets, test touch screen readers too.
• Check zoom, reflow, and forced-colors or high-contrast modes so focus outlines, indentation, and toggle states remain visible.
• Verify that parse errors, copy confirmations, and collapsed summaries are announced once and not repeated endlessly.

Common failure patterns to avoid

• Showing only a prettified code block and calling it “accessible” because it has colors.
• Using identical unlabeled expand buttons for every node.
• Representing booleans, null values, or validation states with color alone.
• Building a custom tree but skipping arrow-key behavior and focus management.
• Firing live-region announcements for every small interaction until the interface becomes noisy.

Conclusion

Designing an accessible JSON formatter for screen readers means translating JSON into usable information, not preserving every visual token. Start with native HTML, use disclosure for most nested branches, reserve tree widgets for truly tree-like interaction, keep raw JSON available as a labeled fallback, and test with real assistive technology. When those pieces are in place, a formatter becomes useful to far more people than the default “pretty print” experience ever will.