Using GitHub Issues with a Screen Reader

Guide Topics

 Skip to content

GitHub Issues are used to track bugs, discuss features, and manage projects. Recent changes to GitHub Issues have improved navigation, particularly for screen reader users. This guide explains how to use the new features effectively, and how to navigate and use GitHub Issues with a screen reader.

Note: This guide provides instructions specific to NVDA on a Windows desktop. Commands and shortcuts may vary for macOS, Linux, or other screen readers.

Prerequisites

  • A GitHub account for managing issues
  • ‘New Issues Experience’ feature preview is enabled
  • Screen reader software installed (e.g., NVDA)

Setup

Screen Reader Modes

Screen readers on Windows generally work in two modes. Although screen readers generally switch to the correct mode automatically, sometimes you have to do it manually:

NVDA: Toggle between “browse” and “focus” modes with NVDA + space. “Focus” mode is indicated by a higher-pitched sound by default, whereas “browse” mode is indicated by a lower-pitched sound.

Note: The NVDA key is usually the Insert or Caps Lock, depending on your settings.

Enabling Feature Preview

From your account, you can view a list of features currently in public preview, each accompanied by a brief description. The new GitHub Issues features are included in this list and must be enabled to use:

Open the User Navigation Menu

  • Sign into your account.
  • If using “browse” mode, navigate to the “Navigation Menu” heading (H or Shift + H), or use D to navigate to the “Repository” navigation section.
  • Navigate to and select the “Open user navigation menu”.

Open Feature Preview

  • Navigate to the “Feature preview” option in the list and select it.

Enable the “New Issues Experience” Public Preview

  • Find the “New Issues Experience” in the feature list and select it.
  • Use Tab to navigate to the “Enable” or “Disable” button at the end of the feature list. This section also contains details about the feature and an option to provide feedback.
  • Confirm that the feature is enabled for your account.

Issues List

GitHub uses lists and clear headings that you can navigate through in different ways depending on your task.

Note: You can press NVDA + F7 to list all links, headings, form fields, buttons, and landmarks.

Locating the Issues List

Once you navigate to a repository’s issues page, you can access a list of issues.

Browse Mode: Locate Issues List

  • Toggle to “browse” mode, if not already in this mode (NVDA + space).
  • Press 1 to navigate to the heading at the top of the page.
  • Press L key to navigate to the “Search Results List”.

Focus Mode: Locate Issues List

  • Press NVDA + space keys to toggle to “focus” mode if not already in this mode.
  • Press the Ctrl + / keys to navigate to the “Search Issues” field.
  • Press Tab key multiple times to navigate to “Search Results List”.

Browse Mode: Navigate to Issues

  • Press NVDA + space to toggle to “browse” mode if not already in this mode.
  • Press H to move to the next issue heading, skipping other content and focusing on issue titles, or
  • Press 3 to move to the next level 3 heading, as issue titles are marked with this heading level, or
  • Press I to navigate to each issue title link item inside the “Search Results List”.
  • Use the ↑ and ↓ keys to read and navigate through the issue details.

Focus Mode: Navigate to Issues

  • Press NVDA + space to toggle to “focus” mode if not already in this mode.
  • Use the ↑ and ↓ keys to read and navigate through the issues.
  • Use Tab to move to the next interactive element.
  • Use Shift + Tab to move to the previous one.

Load More Issues

  • Navigate to the pagination section using Tab from currently focused issue.
  • If using “browse” mode, you can use D to navigate to the “Pagination” navigation section.
  • Select an option to load another set of issues.

Open an Issue

  • Press Enter to open the currently focused issue, or
  • Press Ctrl + Enter to open issue in a new tab.

Defining Search Criteria

You can narrow down the issues list by using the search functionality.

Focus on the Search Field

  • Press the F key to move between form fields, until you reach the “search issues” field.

Define Search Criteria

  • Type keywords like “author”, “project”, “label”, or “milestone” to filter the list.
  • As you start typing, available options will appear in the search box. You can use the ↑ and ↓ keys to navigate between the options. Press Enter to select an option; this will provide additional options for that selection, which you can navigate and select in the same way.
  • Once you have added all the desired search parameters, press Enter to update the list of issues that match your search criteria.

Applying Filters

The actions toolbar provides various options for filtering, sorting, and managing issues. You can navigate this toolbar using only the keyboard.

Note: The filter buttons do not indicate the current filter state. To view the active filter conditions, refer to the issue search box.

Focus on the Toolbar

  • Press Tab from the “search issues” field until you reach the “actions toolbar”, or
  • Press Shift + Tab from issues list until you reach the “Actions toolbar”
  • Use the ← and → keys to move between different options within the toolbar.

Select an Option

  • Once you have focused on the desired option, press Enter to activate it. This could open a dropdown menu or apply a filter.
  • If an option opens a dropdown menu, type or use the ↑ and ↓ keys to move through the menu items.
  • Press Enter to select an item from the dropdown.

Apply Filters

  • Some options may apply filters immediately upon selection. For other dropdown options, you may need to press Esc after making your selections to apply them.

Managing Issues

The issue detail page contains the title, description, labels, and comments. This page is primarily text-based so using “focus” mode is not recommended.

Open Issue Details

Open the Issue

  • Press Enter to open focused issue.
  • Navigate to issue sections (e.g., Description, Activity, Add a comment, Issue actions), using heading level 2 by pressing H or 2.
  • Navigate other issue details (e.g., Assignees, Labels, Type, Projects, Milestone), using heading level 3 by pressing H or 3.

Closing an Issue

If you have the necessary permissions, you will find an option to close the issue after the comment submission form on the issue page:

  • Navigate to the ‘Add a comment’ heading level 2 (Press H or 2 to navigate).

Close Issue

  • Optionally, press Tab until you reach the comment text area and type a comment specifying a reason to close the issue.
  • Navigate and select the “Close” button to close the issue. Use Ctrl + Shift + Enter to close the issue from the comment text area.
  • Alternatively, select the “more options” menu to choose one of the other options to close the issue.

Creating a New Issue

You can create a new issue from either the issues list page or an issue details page.

  • From the issues list page, you can Tab from the search field to the issues list you will encounter the “New Issue” link.
  • From the issue details page, you can Tab from the first heading level 1 on the page to reach the “New Issue” link.

Select the “New Issue”

  • Select the “New Issue” link
  • This will open a blank issue page for the current repository, or
  • If the repository has Issue Templates, a list of templates will appear. Choose a template to open a new issue page with predefined sections.

Fill out Issue Details

  • Once the new issue page is loaded, fill out the form with the issue’s “title” and “description” in the respective fields.
  • You can also enter additional information such as “Assignees”, “Labels”, “Type”, “Projects”, and “Milestone”.

Create New Issue

  • Once finished, tab to the “Submit new issue” button and press Enter, or
  • Use Ctrl + Enter to create the issue from a text area.

Resources

Please share questions or comments on the accessibility community discussion page.

Accessibility Documentation