Skip to main content

Screen reader support

Blockly supports usage with a screen reader starting in Blockly v13. Screen reader support is closely tied to keyboard navigation.

When developing Blockly's screen reader interactions, a guiding principle was that screen reader users should be able to easily collaborate with sighted users. Collaboration is important for pair programming and debugging. To the maximum extent possible, Blockly should just work when used with a screen reader. This page documents the additional text output that is available to a screen reader user, which is presented in parallel with the visual output.

Application role​

Blockly uses the application ARIA role to indicate that it handles all keyboard shortcuts. Block programming cannot be mapped to semantic HTML without losing critical information. For more information on Blockly's approach to accessibility and the justification for this decision, see the accessibility principles page.

Block labels​

Screen readers rely on the aria-label attribute to name elements that do not have visible labels in the DOM. Block labels must give screen reader users information about where they are in a program and what actions they can take at that location. Blockly dynamically calculates labels for blocks based on the block definition, rendered text, and connected blocks. Blockly also uses the aria-roledescription attribute to describe the shape of the block.

Screen readers vary in how they present aria-labels and aria-roledescriptions. The Blockly team tested with JAWS, NVDA, VoiceOver, and ChromeVox during development and selected a labeling strategy that balanced the quirks of these screen readers.

note

The best way to explore block labels is to try it yourself on the Blockly playground with a screen reader enabled.

Block labels are built by combining strings. They may have the following information:

  • Position: the first block in a stack is labeled "begin stack".
  • Available connections: "has input", "has inputs", or no information. Both horizontal (value) and vertical (statement) inputs are considered.
  • Shape: generally "statement", "value", or "container". Statement blocks can be stacked vertically; value blocks can be connected horizontally; container blocks can contain statement blocks.
  • Block and field text: The contents of the block and selected children, generally read from left to right. The label is derived from the text displayed on the block, meaning that it is automatically internationalized.

Extended descriptions​

Screen reader users can replay the block label with I or play an extended description with shift + I. The extended description contains information about parent blocks. This information is disruptive when reading code linearly but helpful when debugging or reorienting within a program.

Fields​

Built-in fields​

Most editable fields in Blockly have an aria-role of "button" to indicate that pressing enter will open a field editor. Blockly sets more specific ARIA roles for built-in fields when appropriate (e.g. text inputs and checkboxes).

Blockly's number fields have an HTML input type of text rather than number. Developers are encouraged to add additional labels and validation about the type of number expected. See the number field documentation for more information.

Custom fields​

Blockly allows developers to create arbitrarily complex custom fields. Developers are responsible for the accessibility of their custom field editors.

Dragging​

During drags Blockly uses an ARIA live region to provide updates on the location of the dragging block. This describes where the block will connect if the drag is immediately confirmed. Updates are generated by both mouse and keyboard drags.

Screen reader optimizations​

During testing we found cases where the preferences of screen reader users strongly diverged from the preferences of sighted users. Blockly exposes a "screen reader mode" that enables settings that were preferred by screen reader users. There is no way for Blockly to detect if a screen reader is in use, so users need to explicitly toggle this mode with control + alt + z (Windows) or command + option + z (Mac). Developers may also expose these options as user preferences for more granular control.

By default navigating down from the last item on a workspace moves the cursor back up to the top of the workspace. This is called "looping". Screen reader users preferred a hard stop, while sighted users preferred looping. In screen reader mode looping is disabled.

Audio cues​

By default Blockly does not play sounds when the cursor moves up and down. In screen reader mode tones play when the cursor moves to a new level of indentation.