Skip to content

Keyboard shortcuts doc #9895

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rachel-fenichel merged 3 commits into from
May 18, 2026
Merged

Keyboard shortcuts doc #9895

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2cb1bde
chore(docs): update keyboard shortcut page for v13
rachel-fenichel May 18, 2026
9a1d93c
chore(docs): update nesting on keyboard nav documentation
rachel-fenichel May 18, 2026
61ab350
chore(docs): remove references to META keycode in favor of CTRL_CMD
rachel-fenichel May 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 13 additions & 5 deletions packages/docs/docs/guides/configure/web/keyboard-nav.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,13 @@ information about the cursor location and **control + enter** (Windows) or
**command + enter** (Mac) to open the context menu. Cut, copy/paste, and
undo/redo all follow conventions for keyboard shortcuts.

## Why not tab?
## Technical details

Blockly keyboard navigation uses the [focus system](/guides/configure/web/focus)
to manage the location of the cursor. This code will be released in Blockly v13
(targeted release: June 2026).

### Why not tab?

Blockly does not follow the convention to navigate around a page with **tab**
and **shift + tab** because block code cannot usefully be compressed into a
Expand All @@ -68,11 +74,13 @@ From a computer science perspective a block program is an abstract syntax tree.
Arrow keys allow for navigation up/down and left/right within the tree, while
tab navigation only supports a fixed order.

## Technical details
### Why single-key shortcuts?

Blockly keyboard navigation uses the [focus system](/guides/configure/web/focus)
to manage the location of the cursor. This code will be released in Blockly v13
(targeted release: June 2026).
Pressing multiple keys at the same time (e.g. `Ctrl + C`) requires manual
dexterity and awareness of keyboard layout that may not be fully developed
by the time children start using Blockly in school. It is also difficult to
create a set of keyboard shortcuts that work across all OS and browser
combinations. Single-key shortcuts address both issues.
Copy link
Copy Markdown
Contributor

@gonfunko gonfunko May 18, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it worth adding a note about the justification of why this doesn't violate the WCAG guidelines?

Copy link
Copy Markdown
Collaborator Author

@rachel-fenichel rachel-fenichel May 18, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Documented in the Compliance section below, as a sub-bullet of the actual rule.


### Compliance

Expand Down
73 changes: 30 additions & 43 deletions packages/docs/docs/guides/configure/web/keyboard-shortcuts.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,10 +7,9 @@ image: images/blockly_banner.png
# Keyboard shortcuts

Blockly maintains a registry of keyboard shortcuts that map keys (or key
combinations like `ctrl-C`) to actions. The registry is
[prepopulated](#default-shortcuts) with a number of shortcuts, such as `ctrl-C`
and `meta-C` for copy. You can add shortcuts to and delete shortcuts from the
registry.
combinations) to actions. The registry is [prepopulated](#default-shortcuts)
with a number of shortcuts, such as `Ctrl + C` and `Command + C` for copy. You
can add shortcuts to and delete shortcuts from the registry.

## How keyboard shortcuts work

Expand Down Expand Up @@ -44,7 +43,8 @@ implements
[`IFocusableNode`](/reference/blockly.ifocusablenode). This
interface is implemented by all Blockly components that the user can focus on,
including workspaces, blocks, fields, comments, and your own custom components;
for more information, see [Focus system](/guides/configure/web/focus).
for more information, see the documentation on the
[focus system](/guides/configure/web/focus).

For example, a `preconditionFn` might use `focusedNode` to ensure that a
shortcut only applies to blocks.
Expand Down Expand Up @@ -73,6 +73,9 @@ const logFieldsShortcut = {
};
```

You can use the shortcut name to associate keyboard shortcuts with
[context menu items](/guides/configure/web/context-menus#keyboard-shortcut).

### preconditionFn (optional)

Blockly calls this function to decide if a shortcut applies to the current
Expand Down Expand Up @@ -128,8 +131,8 @@ const logFieldsShortcut = {
};
```

Although `callback` is optional, there is generally no reason not to implement
it.
Although `callback` is optional, leaving it undefined means your shortcut will
not do anything.

### keyCodes (optional)

Expand All @@ -155,41 +158,21 @@ This is not common.

If your keyboard shortcut is activated by a combination of keys, such as holding
`Control` and `C` simultaneously, create a serialized keycode by calling
`Blockly.ShortcutRegistry.registry.createSerializedKey`:

```js
const ctrlC = Blockly.ShortcutRegistry.registry.createSerializedKey(
Blockly.utils.KeyCodes.C, // Keycode of main key
[Blockly.utils.KeyCodes.CTRL], // Array of modifier keys
);

const copyShortcut = {
// ...
keyCodes: [ctrlC], // Use the serialized keycode
// ...
};
```

#### Control and Meta

On Windows, many shortcuts are activated with the `Control` key. On Mac, these
keyboard shortcuts use the `Command` key instead, which is recognized as the
`META` keycode. To support both operating systems, register your shortcuts with
both the `CTRL` keycode and the `META` keycode.
`Blockly.ShortcutRegistry.registry.createSerializedKey`. On Windows and Linux
many shortcuts are activated with the `Control` key. On Apple plaforms these
keyboard shortcuts use the `Command` key instead. Register your shortcuts with
the `CTRL_CMD` keycode whenever you want your shortcut to use the system's
primary modifier key. Blockly will map the key combination appropriately.

```js
const ctrlC = Blockly.ShortcutRegistry.registry.createSerializedKey(
Blockly.utils.KeyCodes.C,
[Blockly.utils.KeyCodes.CTRL],
);
const metaC = Blockly.ShortcutRegistry.registry.createSerializedKey(
Blockly.utils.KeyCodes.C,
[Blockly.utils.KeyCodes.META],
[Blockly.utils.KeyCodes.CTRL_CMD],
);

const copyShortcut = {
// ...
keyCodes: [ctrlC, metaC],
keyCodes: [ctrlC],
// ...
};
```
Expand Down Expand Up @@ -270,12 +253,16 @@ Blockly.ShortcutRegistry.registry.register(modLogFieldsShortcut);
The shortcut registry is prepopulated with a number of shortcuts. You can find
these in
[https://github.com/RaspberryPiFoundation/blockly/blob/main/packages/blockly/core/shortcut_items.ts](https://github.com/RaspberryPiFoundation/blockly/blob/main/packages/blockly/core/shortcut_items.ts).
The shortcuts are defined in the `registerXxxx` functions.

## Keyboard navigation shortcuts

The [keyboard navigation plugin](/guides/configure/web/keyboard-nav)
contains shortcuts that allow users to navigate Blockly with the keyboard, such
as by using arrow keys. Keyboard navigation is essential for users who cannot
use a mouse, such as those with motor or visual impairments. It is also useful
for power users who may want to use keyboard shortcuts for efficiency.
The shortcuts are defined in the `registerXxxx` functions. You can also view
all currently registered shortcuts by running
`Blockly.ShortcutRegistry.registry.getKeyMap()`.

### Keyboard navigation

Starting in v13, Blockly can be entirely
[controlled from the keyboard](/guides/configure/web/keyboard-nav). Where
possible developers should use the default keyboard navigation shortcuts rather
than overriding or remapping them. Keyboard navigation is essential for users
who cannot use a mouse, such as those with motor or visual impairments. It is
also useful for power users who may want to use keyboard shortcuts for
efficiency.