How to Add Accessible Keyboard Shortcuts in React

Keyboard shortcuts can make an interactive React tool faster to use—but a shortcut that fires while someone is typing, overrides a browser command, or leaves keyboard users without a way to discover it can make the app harder to use. This tutorial builds a React keyboard shortcut with a cleaned-up event listener, modifier-key checks, and safeguards for editable fields.

Key Takeaways

• Register global keyboard listeners in an effect and remove them in its cleanup function.
• Ignore events from inputs, text areas, select controls, contenteditable regions, and textboxes.
• Use a documented modifier-key combination, and call preventDefault() only after confirming the shortcut should run.
• Keep an equivalent visible control and test the interaction using only a keyboard.

Choose a shortcut that respects users

Before writing a listener, decide what the shortcut does, which keys activate it, and when it should be ignored. This example opens a command panel with Ctrl+Shift+L on Windows and Linux or ⌘+Shift+L on macOS.

A modifier combination is usually a safer choice than a bare letter. A single-character shortcut can trigger while someone is entering text or using assistive technology. WCAG 2.1.4 requires single-character shortcuts to be disableable, remappable to include a modifier, or active only when the relevant component has focus. Modifier shortcuts still need care: they can conflict with browser commands, operating-system shortcuts, browser extensions, or other features in your app.

Make the shortcut discoverable—for example, show it beside the command in a menu or provide a keyboard-shortcuts help panel. Keep a visible button or menu command as an alternative; not every user can or wants to use a shortcut.

Add a listener with cleanup

In React, an effect is a suitable place to synchronize a component with a browser event listener. The effect below installs the listener when the component needs it and removes that exact listener when the component unmounts or the callback changes.

import { useEffect } from "react";

function isEditingTarget(event: KeyboardEvent): boolean {
  return event.composedPath().some(
    (node) =>
      node instanceof HTMLElement &&
      (node.isContentEditable ||
        node.matches("input, textarea, select, [role='textbox']")),
  );
}

export function useCommandPanelShortcut(onOpen: () => void): void {
  useEffect(() => {
    function handleKeyDown(event: KeyboardEvent) {
      if (event.defaultPrevented || event.repeat || event.isComposing) return;
      if (isEditingTarget(event)) return;

      const hasPrimaryModifier = event.ctrlKey || event.metaKey;
      const isExpectedCombination =
        hasPrimaryModifier && event.shiftKey && !event.altKey;

      if (!isExpectedCombination || event.key.toLowerCase() !== "l") return;

      // Prevent the browser's default only after this app has matched the shortcut.
      event.preventDefault();
      onOpen();
    }

    window.addEventListener("keydown", handleKeyDown);
    return () => window.removeEventListener("keydown", handleKeyDown);
  }, [onOpen]);
}

event.composedPath() checks the event's path through the DOM, including elements inside a shadow root. The editable-field guard also checks contenteditable elements and elements with the textbox role. If your app uses a custom editor that does not expose one of these signals, add its editing state to the guard rather than assuming every focused element is safe to interrupt.

The listener uses event.key, which represents the key value, and checks the Ctrl or Command modifier along with Shift. It rejects Alt, repeated keydown events, and events during input-method composition. Most importantly, it does not cancel the browser's default action unless the app is actually handling the matching shortcut.

Connect the shortcut to a React component

Keep the callback stable with useCallback so the effect does not needlessly replace the listener after every render. Provide another way to open the panel, such as a button.

import { useCallback, useState } from "react";
import { useCommandPanelShortcut } from "./useCommandPanelShortcut";

export function CommandPanelExample() {
  const [isOpen, setIsOpen] = useState(false);

  const openPanel = useCallback(() => {
    setIsOpen(true);
  }, []);

  useCommandPanelShortcut(openPanel);

  return (
    <>
      <button type="button" onClick={openPanel}>
        Open command panel (Ctrl/⌘+Shift+L)
      </button>

      {isOpen && (
        <section aria-labelledby="command-panel-title">
          <h2 id="command-panel-title">Command panel</h2>
          <button type="button" onClick={() => setIsOpen(false)}>
            Close
          </button>
        </section>
      )}
    </>
  );
}

This example demonstrates opening and closing content; it is not a complete accessible dialog. If the panel behaves like a modal dialog, implement the appropriate dialog semantics and focus behavior: move focus into it when it opens, keep keyboard focus within it while modal, and return focus to the invoking control when it closes. If it is a non-modal panel, decide where focus should go and make that behavior predictable.

The shortcut is global except while the event comes from an editable field. If the action should only apply in a particular part of the interface, add an explicit condition for that context rather than broadening the listener's reach.

Test it with a keyboard

Test the behavior in the browser, not just the shortcut handler in isolation:

1. Use Tab and Shift+Tab to reach the visible button. Confirm it can open the panel and that the shortcut is documented.
2. Focus an input, textarea, select, contenteditable area, and any custom editor. Press the shortcut and confirm it does not trigger the global action or disrupt typing.
3. Focus a non-editable part of the page and press the documented modifier combination. Confirm the panel opens once.
4. Press the shortcut repeatedly or hold the keys. Confirm repeated events do not cause unexpected repeated actions.
5. Open and close the panel with the keyboard. Check that focus remains visible and follows the panel's intended interaction pattern.
6. Test on the supported operating systems and browsers. Check for conflicts with browser, operating-system, and assistive-technology shortcuts.

For a modal panel, also test its focus management and Escape behavior as appropriate. A page-level key listener does not by itself make a dialog, menu, or other widget keyboard accessible; those controls need interaction patterns suited to their roles.

Common Mistakes

• Forgetting cleanup: A listener left attached after a component unmounts can keep doing work or call stale code. Return a cleanup function from the effect.
• Reinstalling the listener on every render: An inline callback changes identity on each render. Stabilize it with useCallback, or design the hook to handle changing callbacks deliberately.
• Triggering while a user types: Checking only input misses textareas, select controls, contenteditable regions, and custom textboxes. Guard the relevant editing surfaces.
• Calling preventDefault() too early: Do it only after the event matches the shortcut and the app is ready to handle it. Avoid suppressing unrelated browser behavior.
• Ignoring conflicts and discoverability: A shortcut that is undocumented or overrides a familiar command can surprise users. Choose deliberately, explain it in the interface, and offer a non-shortcut route.
• Assuming a working shortcut is sufficient accessibility: Users also need keyboard-operable controls, visible focus, and appropriate focus handling when the shortcut opens new UI.

Best Practices

• Prefer a documented modifier combination over an unmodified character for a page-level command.
• Match the intended keys precisely, and ignore repeated events or input-method composition where appropriate.
• Keep the shortcut's action available through the normal interface.
• Scope global listeners to the component or application that needs them, and always clean them up.
• Test with keyboard-only navigation and with real editable controls, not just a synthetic key event.
• Review the shortcut when adding features; a combination that was free before may later conflict with a new command.

Conclusion

A React keyboard shortcut needs more than a keydown handler. Install and clean up the listener correctly, skip editable contexts, check modifiers before acting, document the combination, and keep keyboard access to the same feature through the interface. Then test the full interaction—including focus—not only whether the callback fires.

References

• React: useEffect — effect setup and cleanup for synchronizing with external systems.
• WAI-ARIA Authoring Practices Guide: Keyboard Interface — keyboard interaction and focus considerations.
• WCAG 2.2: Understanding Success Criterion 2.1.4, Character Key Shortcuts — requirements for shortcuts that use only character keys.