{"id":1665,"date":"2025-01-28T17:19:06","date_gmt":"2025-01-28T17:19:06","guid":{"rendered":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/2025\/01\/28\/considerations-for-making-a-tree-view-component-accessible\/"},"modified":"2025-01-28T17:19:06","modified_gmt":"2025-01-28T17:19:06","slug":"considerations-for-making-a-tree-view-component-accessible","status":"publish","type":"post","link":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/2025\/01\/28\/considerations-for-making-a-tree-view-component-accessible\/","title":{"rendered":"Considerations for making a tree view component accessible"},"content":{"rendered":"

Tree views are a core part of the GitHub experience. You\u2019ve encountered one if you\u2019ve ever navigated through a repository\u2019s file structure or reviewed a pull request.<\/p>\n\n

On GitHub, a tree view is the list of folders and the files they contain. It is analogous to the directory structure your operating system uses as a way of organizing things.<\/p>\n

Tree views are notoriously difficult to implement in an accessible way. This post is a deep dive into some of the major considerations that went into how we made GitHub\u2019s tree view component<\/a> accessible. We hope that it can be used as a reference and help others.<\/p>\n

Start with Windows<\/a><\/h2>\n

It\u2019s important to have components with complex interaction requirements map to something people are already familiar with using<\/strong>. This allows for responsiveness to the keypresses they will try to navigate and take action on our tree view instances.<\/p>\n

We elected to adopt Windows File Explorer\u2019s tree view implementation, given the prominence of Windows\u2019 usage<\/a> for desktop screen reader users.<\/p>\n\n

Navigating and taking actions on items in Windows\u2019 tree view using NVDA<\/a> and JAWS<\/a> helped us get a better understanding of how things worked, including factors such as focus management, keyboard shortcuts, and expected assistive technology announcements.<\/p>\n

Then maybe reference the APG<\/a><\/h2>\n

The ARIA Authoring Practices Guide (APG)<\/a> is a bit of an odd artifact. It looks official but is no longer recognized by the W3C as a formal document<\/a>.<\/p>\n

This is to say that the APG can serve as a helpful high-level resource for things to consider for your overall approach, but its suggestions for code necessitate deeper scrutiny.<\/p>\n

Build from a solid, semantic foundation<\/a><\/h2>\n

At its core, a tree view is a list of lists. Because of this, we used ul and li elements for parent and child nodes:<\/p>\n

<ul>
\n <li>
\n <ul>
\n <li>.github\/<\/li>
\n <li>source\/<\/li>
\n <li>test\/<\/li>
\n <\/ul>
\n <\/li>
\n <li>.gitignore<\/li>
\n <li>README.md<\/li>
\n<\/ul><\/p>\n

There are a few reasons for doing this, but the main considerations are:<\/p>\n

Better assurance that a meaningful accessibility tree is generated<\/a>,
\nLessening the work we need for future maintenance, and consequential re-verification that our updates continue to work properly, and
\nBetter guaranteed interoperability between different browsers, apps, and other technologies.<\/p>\n

NOTE<\/strong>: GitHub currently does not virtualize its file trees. We would need to revisit this architectural decision if this ever changes.<\/p>\n

Better broad assistive technology support<\/a><\/h3>\n

The more complicated an interactive pattern is, the greater the risk that there are bugs or gaps with assistive technology support<\/a>.<\/p>\n

Given the size of the audience GitHub serves, it\u2019s important that we consider more than just majority share assistive technology<\/a> considerations.<\/p>\n

We found that utilizing semantic HTML elements also performed better for some less-common assistive technologies. This was especially relevant with some lower-power devices, like an entry-level Android smartphone from 2021.<\/p>\n

Better Forced Color Mode support<\/a><\/h3>\n

Semantic HTML elements also map to native operating system UI patterns, meaning that Forced Color Mode<\/a>\u2019s heuristics will recognize them without any additional effort. This is helpful for people who rely on the mode to see screen content.<\/p>\n

The heuristic mapping behavior does not occur if we used semantically neutral div or span elements, and would have to be manually recreated and maintained.<\/p>\n

Use a composite widget<\/a><\/h2>\n

A composite widget<\/a> allows a component that contains multiple interactive elements to only require one tab stop unless someone chooses to interact with it further.<\/p>\n

Consider a file tree for a repository that contains 500+ files in 20+ directories. Without a composite widget treatment, someone may have to press Tab far too many times to bypass the file tree component and get what they need.<\/p>\n

Think about wrapping it in a landmark<\/a><\/h2>\n

Like using a composite widget, landmark regions<\/a> help some people quickly and efficiently navigate through larger overall sections of the page. Because of this, we wrapped the entire file tree in a nav landmark element<\/a>.<\/p>\n

This does not mean every tree view component should be a landmark, however! We made this decision for the file tree because it is frequently interacted with as a way to navigate through a repository\u2019s content<\/a>.<\/p>\n

Go with a roving tabindex approach<\/a><\/h2>\n

A roving tabindex<\/a> is a technique that uses tabindex=”-1″ applied to each element in a series, and then updates the tabindex value to use 0 instead in response to user keyboard input. This allows someone to traverse the series of elements, as focus \u201croves\u201d to follow their keypresses.<\/p>\n

<li tabindex=”-1″>File 1<\/li>
\n<li tabindex=”-1″>File 2<\/li>
\n<li tabindex=”0″>File 3<\/li>
\n<li tabindex=”-1″>File 4<\/li><\/p>\n

The roving tabindex approach performed better than utilizing aria-activedescendant<\/a>, which had issues with VoiceOver on macOS and iOS.<\/p>\n

Enhance with ARIA<\/a><\/h2>\n

We use a considered set of ARIA<\/a> declarations to build off our semantic foundation.<\/p>\n

Note that while we intentionally started with semantic HTML, there are certain ARIA declarations that are needed. The use of ARIA here is necessary and intentional, as it expands the capabilities of HTML to describe something that HTML alone cannot describe\u2014a tree view construct.<\/p>\n

Our overall approach follows what the APG suggests<\/a>, in that we use the following:<\/p>\n

role=”tree” is placed on the parent ul element, to communicate that it is a tree view construct.
\nrole=”treeitem” is placed on the child li elements, to communicate that they are tree view nodes.
\nrole=”group” is declared on child ul elements, to communicate that they contain branch and leaf nodes.
\naria-expanded is declared on directories, with a value of true to communicate that the branch node is in an opened state and a value of false to communicate that it is in a collapsed state instead.
\naria-selected is used to indicate if branch or leaf nodes have been chosen by user navigation, and can therefore have user actions applied to them.<\/p>\n

We also made the following additions:<\/p>\n

aria-hidden=”true” is applied to SVG icons (folders, files, etc.) to ensure its content is not announced.
\naria-current=”true” is placed on the selected node to better support when a node is deep linked to via URL.<\/p>\n

NOTE<\/strong>: We use \u201cbranch node\u201d and \u201cleaf node\u201d as broad terms that can apply to all tree view components we use on GitHub. For the file tree, branch nodes would correspond to directories and subdirectories, and leaf nodes would correspond to files.<\/p>\n

Support expected navigation techniques<\/a><\/h2>\n

The following behaviors are what people will try when operating a tree view construct, so we support them:<\/p>\n

Keyboard keypresses<\/a><\/h3>\n

Tab: Places focus on the entire tree view component, then moves focus to the next focusable item on the view.
\nEnter:<\/p>\n

If a branch node is selected: Displays the directory\u2019s contents.
\nIf a leaf node is selected: Displays the leaf node\u2019s contents. <\/p>\n

Down: Moves selection to the next node that can be selected without opening or closing a node.
\nUp: Moves selection to the previous node that can be selected without opening or closing a node.
\nRight:<\/p>\n

If a branch node is selected and in a collapsed state: Expands the selected collapsed branch node and does not move selection.
\nIf a branch node is selected and in an expanded state: Moves selection to the directory\u2019s first child node. <\/p>\n

Left:<\/p>\n

If a branch node is selected and in an expanded state: Collapses the selected collapsed directory node and does not move selection.
\nIf a branch node is selected and in a collapsed state: Moves selection to the node\u2019s parent directory.
\nIf a leaf node is selected: Moves selection to the leaf node\u2019s parent directory. <\/p>\n

End: Moves selection to the last node that can be selected.
\nHome: Moves selection to the first node that can be selected.<\/p>\n

We also support typeahead selection<\/strong>, as we are modeling Windows File Explorer\u2019s tree view behaviors. Here, we move selection to the node closest to the currently selected node whose name matches what the user types.<\/p>\n

Middle clicking<\/a><\/h3>\n

Nodes on tree view constructs are tree items<\/a>, not links. Because of this, tree view nodes do not support the behaviors you get with using an anchor element, such as opening its URL in a new tab or window.<\/p>\n

We use JavaScript to listen for middle clicks and Control+Enter keypresses to replicate this behavior.<\/p>\n

Consider states<\/a><\/h2>\n

Loading<\/a><\/h3>\n

Tree views on GitHub can take time to retrieve their content, and we may not always know how much content a branch node contains.<\/p>\n\n

Live region<\/a> announcements are tricky to get right<\/a>, but integral to creating an equivalent experience. We use the following announcements:<\/p>\n

If there is a known amount of nodes that load, we enumerate the incoming content with an announcement that reads, \u201cLoading {x} items.\u201d
\nIf there is an unknown number of nodes that load, we instead use a more generic announcement of, \u201cLoading\u2026\u201d
\nIf there are no nodes that load we use an announcement message that reads, \u201c{branch node name} is empty.\u201d<\/p>\n

Additionally, we manage focus<\/a> for loading content:<\/p>\n

If focus is placed on a placeholder loading node when the content loads in: Move focus from the placeholder node to the first child node in the branch node.
\nIf focus is on a placeholder loading node but the branch node does not contain content: Move focus back to the branch node. Additionally, we remove the branch node\u2019s aria-expanded declaration.<\/p>\n

Errors<\/a><\/h3>\n

Circumstances can conspire to interfere with a tree view component\u2019s intended behavior. Examples of this could be a branch node failing to retrieve content or a partial system outage<\/a>.<\/p>\n

In these scenarios, the tree view component will use a straightforward dialog component<\/a> to communicate the error.<\/p>\n

Fix interoperability issues<\/a><\/h2>\n

As previously touched on, complicated interaction patterns run the risk of compatibility issues. Because of this, it\u2019s essential to test your efforts with actual assistive technology to ensure it actually works<\/strong>.<\/p>\n

We made the following adjustments to provide better assistive technology support:<\/p>\n

Use aria-level<\/a><\/h3>\n

Screen readers can report on the depth of a nested list item. For example, a li element placed inside of a ul element nested three levels deep can announce itself as such.<\/p>\n

We found that we needed to explicitly declare the level on each li element to recreate this behavior for a tree view. For our example, we\u2019d also need to set aria-level=”3″ on the li element.<\/p>\n

This fix addressed multiple forms of assistive technology we tested with.<\/p>\n

Explicitly set the node\u2019s accessible name on the li element<\/a><\/h3>\n

A node\u2019s accessible name<\/a> is typically set by the text string placed inside the li element:<\/p>\n

<li>README.md<\/li><\/p>\n

However, we found that VoiceOver on macOS<\/a> and iOS<\/a> did not support this. This may be because of the relative complexity of each node\u2019s inner DOM structure.<\/p>\n

We used aria-labelledby to get around this problem, with a value that pointed to the id set on the text portion of each node:<\/p>\n

<li aria-labelledby=”readme-md”>
\n <div>
\n <!– Icon –>
\n <\/div>
\n <div id=”readme-md”>
\n README.md
\n <\/div>
\n<\/li><\/p>\n

This guarantees that:<\/p>\n

the node\u2019s accessible name is announced when focus is placed on the li element,
\nand that the announcement matches what is shown visually.<\/p>\n

Where we\u2019d like to go from here<\/a><\/h2>\n

There\u2019s a couple areas we\u2019re prototyping and iterating on to better serve our users:<\/p>\n

Supporting links inside a node<\/a><\/h3>\n

Browsers apply a lot of behaviors to anchor elements, such as the ability to copy the URL.<\/p>\n

We\u2019d like to replace the JavaScript that listens for middle clicks with a more robust native solution, only without sacrificing interoperability and assistive technology support.<\/p>\n

Supporting multiple actions per node<\/a><\/h3>\n

Tree views constructs were designed assuming a user will only ever navigate to a node and activate it.<\/p>\n

GitHub has use cases that require actions other than activating the node, and we\u2019re exploring how to accomplish that. This is exciting, as it represents an opportunity to evolve the tree view construct on the web.<\/p>\n

Always learning<\/a><\/h2>\n

An accessible tree view is a complicated component to make, and it requires a lot of effort and testing to get right. However, this work helps to ensure that everyone can use a core part of GitHub, regardless of device, circumstance, or ability.<\/p>\n

We hope that highlighting the considerations that went into our work can help you on your accessibility journey.\n<\/p>\n

\n

Share your experience: We\u2019d love to hear from you<\/a> if you\u2019ve run into issues using our tree view component with assistive technology. This feedback is invaluable to helping us continue to make GitHub more accessible.<\/p>\n<\/div>\n

The post Considerations for making a tree view component accessible<\/a> appeared first on The GitHub Blog<\/a>.<\/p>","protected":false},"excerpt":{"rendered":"

Tree views are a core part of the GitHub experience. You\u2019ve encountered one if you\u2019ve ever navigated through a repository\u2019s […]<\/p>\n","protected":false},"author":0,"featured_media":0,"comment_status":"","ping_status":"","sticky":false,"template":"","format":"standard","meta":{"site-sidebar-layout":"default","site-content-layout":"","ast-site-content-layout":"default","site-content-style":"default","site-sidebar-style":"default","ast-global-header-display":"","ast-banner-title-visibility":"","ast-main-header-display":"","ast-hfb-above-header-display":"","ast-hfb-below-header-display":"","ast-hfb-mobile-header-display":"","site-post-title":"","ast-breadcrumbs-content":"","ast-featured-img":"","footer-sml-layout":"","ast-disable-related-posts":"","theme-transparent-header-meta":"","adv-header-id-meta":"","stick-header-meta":"","header-above-stick-meta":"","header-main-stick-meta":"","header-below-stick-meta":"","astra-migrate-meta-layouts":"default","ast-page-background-enabled":"default","ast-page-background-meta":{"desktop":{"background-color":"var(--ast-global-color-4)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""},"tablet":{"background-color":"","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""},"mobile":{"background-color":"","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""}},"ast-content-background-meta":{"desktop":{"background-color":"var(--ast-global-color-5)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""},"tablet":{"background-color":"var(--ast-global-color-5)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""},"mobile":{"background-color":"var(--ast-global-color-5)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""}},"footnotes":""},"categories":[8],"tags":[],"class_list":["post-1665","post","type-post","status-publish","format-standard","hentry","category-github-engineering"],"_links":{"self":[{"href":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/wp-json\/wp\/v2\/posts\/1665","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/wp-json\/wp\/v2\/types\/post"}],"replies":[{"embeddable":true,"href":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/wp-json\/wp\/v2\/comments?post=1665"}],"version-history":[{"count":0,"href":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/wp-json\/wp\/v2\/posts\/1665\/revisions"}],"wp:attachment":[{"href":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/wp-json\/wp\/v2\/media?parent=1665"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/wp-json\/wp\/v2\/categories?post=1665"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/rssfeedtelegrambot.bnaya.co.il\/index.php\/wp-json\/wp\/v2\/tags?post=1665"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}