aria-keyshortcuts — Exposing Keyboard Shortcuts to Assistive Technology

In this tutorial, you will learn about aria. We cover key concepts, practical examples, and best practices to help you master this topic.

aria-keyshortcuts exposes available keyboard shortcuts to screen readers, allowing users to discover and use keyboard commands without memorizing them beforehand.

In this tutorial, you'll learn how to use aria-keyshortcuts in ARIA.

What You'll Learn

By the end of this lesson, you'll understand the aria-keyshortcuts syntax, how to define shortcut combinations, and best practices for exposing keyboard shortcuts.

Why It Matters

Keyboard shortcuts improve efficiency for all users, but they are invisible. aria-keyshortcuts makes them discoverable to screen reader users.

Real-World Use

Doda Browser's developer tools use aria-keyshortcuts so screen reader users discover shortcuts like Ctrl+Shift+I for opening the inspector.

Shortcut Discovery

flowchart LR
  A[User focuses element] --> B[Screen reader checks aria-keyshortcuts]
  B --> C{Shortcut exists?}
  C -->|Yes| D[Announce shortcut]
  C -->|No| E[Standard announcement]
  D --> F[User can use shortcut]
  F --> G[Screen reader shows shortcut in help menu]

How aria-keyshortcuts Works

aria-keyshortcuts uses a string of modifier keys and main keys:

<button aria-keyshortcuts="Ctrl+Shift+S">
  Save Scan Results
</button>

The screen reader announces: "Save Scan Results, button, shortcut Ctrl+Shift+S".

Syntax Rules

Keys are separated by a plus sign. Multiple shortcuts use a space separator:

<!-- Single shortcut -->
<button aria-keyshortcuts="Alt+S">
  Scan
</button>

<!-- Multiple alternative shortcuts -->
<button aria-keyshortcuts="Ctrl+Enter Meta+Enter">
  Run
</button>

<!-- Arrow keys -->
<button aria-keyshortcuts="Up Down Left Right">
  Navigate
</button>

Common Key Names

Best Practices

aria-keyshortcuts only announces the shortcut. You must implement the actual keyboard handler separately:

document.addEventListener('keydown', (event) => {
  if (event.ctrlKey && event.shiftKey && event.key === 'S') {
    event.preventDefault();
    saveResults();
  }
});

Common Mistakes

• Declaring shortcuts that do not work: The attribute must match the actual implementation.
• Using incorrect key names: Follow the standard key naming (Ctrl, Alt, Shift, Meta).
• Forgetting platform differences: Mac uses Cmd instead of Ctrl. Use platform-specific shortcuts.
• Overloading common browser shortcuts: Do not override Ctrl+S, Ctrl+P, etc.
• Not testing with screen readers: The announcement format varies between screen reader and browser combinations.

Practice and Challenge

1. What does aria-keyshortcuts do? Exposes available keyboard shortcuts to screen readers.

2. What is the syntax for a shortcut with Ctrl and S? aria-keyshortcuts="Ctrl+S".

3. How do you specify multiple alternative shortcuts? Separate them with a space: "Ctrl+S Alt+S".

4. Does aria-keyshortcuts implement the shortcut? No. You must implement the key handler separately.

5. Challenge: Add aria-keyshortcuts to three buttons in a toolbar and implement the corresponding keyboard handlers.

FAQ

Mini Project

Create a toolbar with buttons for New, Open, Save, and Print. Add aria-keyshortcuts to each button with standard shortcuts. Implement the keyboard handlers.

What's Next

Continue to ARIA Project to build a complete accessible tab panel with all learned concepts.