idea Hierarchical Text Structure in Map Legend with Group layers for Screen Readers in ArcGIS JavaScript Maps SDK Ideas

Hierarchical Text Structure in Map Legend with Group layers for Screen Readers

stephengsavage — Wed, 01 Oct 2025 22:11:02 GMT

We are using the legend component from the ArcGIS SDK for JavaScript to display data organized in 3-level hierarchies (eg. Community Facilities → Existing Conditions → Places of Worship). In order to provide WCAG 2.1 AA accessibility standards (Section 1.3.1) compliant products the current legend does not support a hierarchical heading structure that is accessible to screen readers.

At present, all legend elements—including the title, group layer names, and individual sublayer names—are rendered using the same heading level (<h5>).
This uniform structure limits accessibility, as screen readers rely on semantic heading levels to interpret and navigate content effectively.
While the SDK provides a heading Level property, it only allows setting a single heading level (e.g., <h3>), which is applied uniformly across all legend items.
There is no built-in functionality to assign different heading levels based on the layer hierarchy (e.g., <h1> for the legend title, <h2> for group layers, and <h3> for sublayers).
To meet accessibility standards, the legend should ideally follow a semantic structure such as: <h1> for the main legend title, <h2> for group or parent layers, and <h3> for individual sublayers
This structure would allow screen readers to interpret and navigate the legend content more meaningfully.

Without proper heading hierarchy, screen reader users cannot understand the relationship between map legend items or navigate efficiently through nested layers, making the map effectively unusable for blind/low-vision users. It's a legal compliance blocker for public-sector organizations and creates accessibility barriers that violate ADA requirements.

Re: Hierarchical Text Structure in Map Legend with Group layers for Screen Readers

NicholasLeBoeuf — Thu, 02 Oct 2025 12:30:18 GMT

I strongly support this request. This enhancement is critical for delivering accessible, public-facing applications that meet WCAG 2.1 AA standards. The current limitation - rendering all legend elements with a uniform heading level - creates significant barriers for screen reader users, who rely on semantic heading structures to understand and navigate content. Enabling differentiated heading levels (e.g., <h1> for the legend title, <h2> for group layers, and <h3> for sublayers) would enable meaningful interpretation of nested legend items and improve compliance with ADA requirements. This is especially important for public-sector projects where accessibility is not optional. I strongly endorse this idea as a necessary fix - not just a feature request - to ensure inclusive design and legal compliance.

Re: Hierarchical Text Structure in Map Legend with Group layers for Screen Readers

BenjaminJimenez — Thu, 02 Oct 2025 13:54:58 GMT

This enhancement is critical for achieving WCAG 2.1 AA compliance and improving the usability of the ArcGIS JavaScript SDK legend component. The current implementation, which uniformly applies a single headingLevel property (e.g., <h5>) across all elements unlike depicted in the documentation, fails to establish the necessary semantic hierarchy.

The proposed solution requires two key technical changes: first, addressing the headingLevel property to allow distinct level for the title to be assigned, and second, implementing a system to map heading levels to the layer hierarchy (ex: <h1> for title, <h2> for group layers, 3 for sublayers). This change is mandatory for screen reader accessibility, as the current flat structure prevents meaningful content navigation and relationship parsing.

Re: Hierarchical Text Structure in Map Legend with Group layers for Screen Readers - Status changed to: Under Consideration

Sage_Wall — Thu, 02 Oct 2025 14:59:33 GMT

We've also received a enhancement request for this though the official support process. We will work with our accessibility team to make appropriate changes.