---
description: Screen reader support in Blockly
title: Screen reader
image: images/blockly_banner.png
---

# Screen reader support

Blockly supports usage with a screen reader starting in Blockly v13. Screen
reader support is closely tied to 
[keyboard navigation](/guides/configure/web/keyboard-nav). 

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](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/application_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](/guides/design/accessibility)
page.

## Block labels

Screen readers rely on the [`aria-label` attribute](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label)
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](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-roledescription)
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](https://raspberrypifoundation.github.io/blockly/packages/blockly/tests/playground.html)
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](/guides/create-custom-blocks/fields/built-in-fields/number#accessibility)
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](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Guides/Live_regions)
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.

### Navigation looping

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. 