![\"Browsing](\"https:\/\/github.blog\/wp-content\/uploads\/2025\/01\/github-repo-browser.png?w=1024&resize=1024%2C653\")
<\/p>\nTree views are a core part of the GitHub experience. You’ve encountered one if you’ve ever navigated through a repository’s file structure or reviewed a pull request.<\/p>\n
<\/p>\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’s tree view component<\/a> accessible. We hope that it can be used as a reference and help others.<\/p>\n It’s 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’s tree view implementation, given the prominence of Windows’ usage<\/a> for desktop screen reader users.<\/p>\n Navigating and taking actions on items in Windows’ 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 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 At its core, a tree view is a list of lists. Because of this, we used There are a few reasons for doing this, but the main considerations are:<\/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 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’s 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 Semantic HTML elements also map to native operating system UI patterns, meaning that Forced Color Mode<\/a>’s 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 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<\/kbd> far too many times to bypass the file tree component and get what they need.<\/p>\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 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’s content<\/a>.<\/p>\n A roving tabindex<\/a> is a technique that uses The roving 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—a tree view construct.<\/p>\n Our overall approach follows what the APG suggests<\/a>, in that we use the following:<\/p>\n We also made the following additions:<\/p>\n NOTE<\/strong>: We use “branch node” and “leaf node” 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 The following behaviors are what people will try when operating a tree view construct, so we support them:<\/p>\n We also support typeahead selection<\/strong>, as we are modeling Windows File Explorer’s 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 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<\/kbd>+Enter<\/kbd> keypresses to replicate this behavior.<\/p>\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 Live region<\/a> announcements are tricky to get right<\/a>, but integral to creating an equivalent experience. We use the following announcements:<\/p>\n Additionally, we manage focus<\/a> for loading content:<\/p>\n Circumstances can conspire to interfere with a tree view component’s 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 As previously touched on, complicated interaction patterns run the risk of compatibility issues. Because of this, it’s 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 Screen readers can report on the depth of a nested list item. For example, a We found that we needed to explicitly declare the level on each This fix addressed multiple forms of assistive technology we tested with.<\/p>\n A node’s accessible name<\/a> is typically set by the text string placed inside the 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’s inner DOM structure.<\/p>\n We used This guarantees that:<\/p>\n There’s a couple areas we’re prototyping and iterating on to better serve our users:<\/p>\n Browsers apply a lot of behaviors to anchor elements, such as the ability to copy the URL.<\/p>\n We’d 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 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’re exploring how to accomplish that. This is exciting, as it represents an opportunity to evolve the tree view construct on the web.<\/p>\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.Start with Windows<\/span><\/a><\/h2>\n
![\"A](\"https:\/\/github.blog\/wp-content\/uploads\/2025\/01\/windows-file-explorer.png?w=1024&resize=1024%2C783\")
<\/p>\nThen maybe reference the APG<\/span><\/a><\/h2>\n
Build from a solid, semantic foundation<\/span><\/a><\/h2>\n
ul<\/code> and li<\/code> 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>\n<\/code><\/pre>\n\n
Better broad assistive technology support<\/span><\/a><\/h3>\n
Better Forced Color Mode support<\/span><\/a><\/h3>\n
div<\/code> or span<\/code> elements, and would have to be manually recreated and maintained.<\/p>\nUse a composite widget<\/span><\/a><\/h2>\n
Think about wrapping it in a landmark<\/span><\/a><\/h2>\n
nav<\/code> landmark element<\/a>.<\/p>\nGo with a roving
tabindex<\/code> approach<\/span><\/a><\/h2>\ntabindex=\"-1\"<\/code> applied to each element in a series, and then updates the tabindex<\/code> value to use 0<\/code> instead in response to user keyboard input. This allows someone to traverse the series of elements, as focus “roves” 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>\n<\/code><\/pre>\ntabindex<\/code> approach performed better than utilizing aria-activedescendant<\/code><\/a>, which had issues with VoiceOver on macOS and iOS.<\/p>\nEnhance with ARIA<\/span><\/a><\/h2>\n
\n
role=\"tree\"<\/code> is placed on the parent ul<\/code> element, to communicate that it is a tree view construct. <\/li>\nrole=\"treeitem\"<\/code> is placed on the child li<\/code> elements, to communicate that they are tree view nodes. <\/li>\nrole=\"group\"<\/code> is declared on child ul<\/code> elements, to communicate that they contain branch and leaf nodes. <\/li>\naria-expanded<\/code> is declared on directories, with a value of true<\/code> to communicate that the branch node is in an opened state and a value of false<\/code> to communicate that it is in a collapsed state instead. <\/li>\naria-selected<\/code> is used to indicate if branch or leaf nodes have been chosen by user navigation, and can therefore have user actions applied to them.<\/li>\n<\/ul>\n\n
aria-hidden=\"true\"<\/code> is applied to SVG icons (folders, files, etc.) to ensure its content is not announced. <\/li>\naria-current=\"true\"<\/code> is placed on the selected node to better support when a node is deep linked to via URL.<\/li>\n<\/ul>\nSupport expected navigation techniques<\/span><\/a><\/h2>\n
Keyboard keypresses<\/span><\/a><\/h3>\n
\n
\n
\n
\n
Middle clicking<\/span><\/a><\/h3>\n
Consider states<\/span><\/a><\/h2>\n
Loading<\/span><\/a><\/h3>\n
![\"A](\"https:\/\/github.blog\/wp-content\/uploads\/2025\/01\/tree-view-loading-nodes.png?w=890&resize=890%2C282\")
<\/p>\n\n
\n
aria-expanded<\/code> declaration.<\/li>\n<\/ul>\nErrors<\/span><\/a><\/h3>\n
Fix interoperability issues<\/span><\/a><\/h2>\n
Use
aria-level<\/code><\/span><\/a><\/h3>\nli<\/code> element placed inside of a ul<\/code> element nested three levels deep can announce itself as such.<\/p>\nli<\/code> element to recreate this behavior for a tree view. For our example, we’d also need to set aria-level=\"3\"<\/code> on the li<\/code> element.<\/p>\nExplicitly set the node’s accessible name on the
li<\/code> element<\/span><\/a><\/h3>\nli<\/code> element:<\/p>\n<li>README.md<\/li>\n<\/code><\/pre>\naria-labelledby<\/code> to get around this problem, with a value that pointed to the id<\/code> 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>\n<\/code><\/pre>\n\n
li<\/code> element, <\/li>\nWhere we’d like to go from here<\/span><\/a><\/h2>\n
Supporting links inside a node<\/span><\/a><\/h3>\n
Supporting multiple actions per node<\/span><\/a><\/h3>\n
Always learning<\/span><\/a><\/h2>\n
\n