How to use a screen reader - Sourcegraph docs

Screen readers are tools that are used by users who are blind or have limited vision to navigate and describe webpages. It is important that we understand how to correctly use them when building our application.

Depending on the platform, there are two widely used screen readers. Although they provide different controls, they ultimately parse webpages in a similar manner. You should not feel that you need to test a page using both screen readers, one is sufficient.

VoiceOver (MacOS)

VoiceOver is already available on MacOS, no download is required.

Video tutorial

Cheatsheet

Shortcut	Action
`Command` + `F5`	Enable/Disable VoiceOver
`Control`	Stop talking
`Control` + `Option` + `Space`	Click
`Control` + `Option` + `→`	Navigate to next line
`Control` + `Option` + `←`	Navigate to previous line
`Control` + `Option` + `Command` + `H`	Navigate to next heading
`Control` + `Option` + `Command` + `Shift` + `H`	Navigate to previous heading

NVDA (Windows)

Download at https://www.nvaccess.org/download/

Video tutorial

Cheatsheet

Shortcut	Action
`Control` + `Alt` + `N`	Enable/disable NVDA
`Caps Lock`	Stop talking
`Enter`	Click
`↓`	Navigate to next line
`↑`	Navigate to previous line
`H`	Navigate to next heading
`Shift` + `H`	Navigate to previous heading

Tips

Use aria-hidden to hide decorative elements from screen readers.
Use ReachUI's <VisuallyHidden /> to provide accessible text that is visually hidden from the UI. This is useful for communicating the semantic meaning of buttons or other elements which are visually represented with an icon or other purely graphical content.
- Note: VisuallyHidden and sr-only can sometimes cause visual bugs. See this related Chromium bug report. We should only use this approach where it is not possible to use an equivalent aria- attribute.
Provide a more specific aria-label to elements whose exact meaning requires context around it to understand.
- For example, in a list of items where each item also has a button associated with it, the button should be aria-labeled to more clearly indicate which item the button is for.
Use screenReaderAnnounce to communicate messages about implied changing state (e.g. form submission, async resolutions, or changes to on-screen data from polling).
Use landmark roles such as role="region" to identify areas with multiple pieces of content that users would want to navigate to easily.