Skip to content

Shortcuts

One registry for every keyboard shortcut, the sheet that lists them and a switch for single keys.

<div class="cap-specimen-row">
  <span><kbd>Esc</kbd></span>
  <span><kbd>Ctrl K</kbd></span>
  <span><kbd>g</kbd> <kbd>o</kbd></span>
  <span><kbd>⌘</kbd> <kbd>K</kbd></span>
  <span><kbd class="cap-kbd">?</kbd></span>
</div>
<div class="cap-specimen-row" data-density="comfortable">
  <span><kbd>Ctrl K</kbd></span>
  <span><kbd>g</kbd> <kbd>o</kbd></span>
</div>

Installation

// package.json: "capsomer": "github:DrDustinEdwards/capsomer#v0.152.2"
import "capsomer/tokens.css";
import "capsomer/base.css";
import "capsomer/shortcuts.css";
import { enhance } from "capsomer/behavior/shortcuts";

enhance();

Usage

<dialog class="cap-dialog cap-keys" data-cap="shortcuts" data-placement="center" data-size="md" aria-labelledby="keys-title">
  <div class="cap-dialog-header" data-divider>
    <h2 class="cap-dialog-title" id="keys-title">Keyboard shortcuts</h2>
  </div>
  <div class="cap-dialog-body cap-keys-body" data-cap-part="keys-list">
    <!-- filled: <div class="cap-keys-group"><h3 class="cap-keys-group-title">Go to</h3>
         <dl class="cap-keys-list"><div><dt><kbd>g</kbd> <kbd>o</kbd></dt><dd>Go to Overview<span class="cap-keys-about">Problems first, worst first.</span></dd></div></dl></div> -->
  </div>
  <div class="cap-dialog-footer" data-align="start">
    <div class="cap-keys-foot">
      <label class="cap-switch"><input type="checkbox" role="switch" data-cap-part="single-keys" aria-describedby="keys-note" checked><span>Single-key shortcuts</span><span class="cap-switch-state" aria-hidden="true">On</span></label>
      <p class="cap-keys-note" id="keys-note">Turn these off if they clash with a screen reader or speech input. It applies at once. Shortcuts with Ctrl or ⌘ keep working.</p>
    </div>
  </div>
  <button type="button" class="cap-btn cap-dialog-close" data-variant="quiet" data-icon-only data-cap-part="close" aria-label="Close"><svg>…</svg></button>
</dialog>
<button type="button" class="cap-btn" data-cap-keys-open>Keyboard shortcuts <kbd>?</kbd></button>
import { register, enhance } from "capsomer/behavior/shortcuts";
enhance();
const off = register({ key: "g o", label: "Go to Overview", about: "Problems first, worst first.", group: "Go to", run: () => go("/") });
register({ key: "Mod+k", label: "Open the command menu", group: "General", run: openCommandMenu });
// off() removes it again.

Examples

Working: press ? or g then o

<main class="specimen-page" tabindex="-1">
  <h1>Overview</h1>
  <p>Press <kbd>?</kbd> for the sheet, <kbd>g</kbd> then <kbd>o</kbd> to go to Overview, <kbd>r</kbd> to refresh. Keys typed into the field below are left alone.</p>
  <p><button type="button" class="cap-btn" data-cap-keys-open>Keyboard shortcuts</button></p>
  <p><label for="note">A note</label> <input id="note" class="cap-input" type="text" autocomplete="off" /></p>
  <p role="status" data-specimen-part="said"></p>
</main>

The sheet, open

<main class="specimen-page" tabindex="-1">
  <h1>Overview</h1>
  <p>The page behind the sheet.</p>
</main>
<dialog class="cap-dialog cap-keys" data-cap="shortcuts" data-placement="center" data-size="md" aria-labelledby="keys-title">
  <div class="cap-dialog-header" data-divider>
    <h2 class="cap-dialog-title" id="keys-title">Keyboard shortcuts</h2>
  </div>
  <div class="cap-dialog-body cap-keys-body" data-cap-part="keys-list"></div>
  <div class="cap-dialog-footer" data-align="start">
    <div class="cap-keys-foot">
      <label class="cap-switch"><input type="checkbox" role="switch" data-cap-part="single-keys" aria-describedby="keys-note" checked /><span>Single-key shortcuts</span><span class="cap-switch-state" aria-hidden="true">On</span></label>
      <p class="cap-keys-note" id="keys-note">Turn these off if they clash with a screen reader or speech input. It applies at once. Shortcuts with Ctrl or ⌘ keep working.</p>
    </div>
  </div>
  <button type="button" class="cap-btn cap-dialog-close" data-variant="quiet" data-icon-only data-cap-part="close" aria-label="Close"><svg viewBox="0 0 16 16" width="16" height="16" aria-hidden="true" focusable="false"><path d="M4 4l8 8M12 4l-8 8" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" /></svg></button>
</dialog>

The sheet, single-key shortcuts off

<main class="specimen-page" tabindex="-1">
  <h1>Overview</h1>
  <p>The page behind the sheet.</p>
</main>
<dialog class="cap-dialog cap-keys" data-cap="shortcuts" data-placement="center" data-size="md" aria-labelledby="off-title">
  <div class="cap-dialog-header" data-divider>
    <h2 class="cap-dialog-title" id="off-title">Keyboard shortcuts</h2>
  </div>
  <div class="cap-dialog-body cap-keys-body" data-cap-part="keys-list"></div>
  <div class="cap-dialog-footer" data-align="start">
    <div class="cap-keys-foot">
      <label class="cap-switch"><input type="checkbox" role="switch" data-cap-part="single-keys" aria-describedby="off-note" /><span>Single-key shortcuts</span><span class="cap-switch-state" aria-hidden="true">Off</span></label>
      <p class="cap-keys-note" id="off-note">Turn these off if they clash with a screen reader or speech input. It applies at once. Shortcuts with Ctrl or ⌘ keep working.</p>
    </div>
  </div>
  <button type="button" class="cap-btn cap-dialog-close" data-variant="quiet" data-icon-only data-cap-part="close" aria-label="Close"><svg viewBox="0 0 16 16" width="16" height="16" aria-hidden="true" focusable="false"><path d="M4 4l8 8M12 4l-8 8" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" /></svg></button>
</dialog>

The sheet, comfortable density

<main class="specimen-page" tabindex="-1">
  <h1>Overview</h1>
  <p>The page behind the sheet.</p>
</main>
<dialog class="cap-dialog cap-keys" data-cap="shortcuts" data-placement="center" data-size="md" data-density="comfortable" aria-labelledby="comf-title">
  <div class="cap-dialog-header" data-divider>
    <h2 class="cap-dialog-title" id="comf-title">Keyboard shortcuts</h2>
  </div>
  <div class="cap-dialog-body cap-keys-body" data-cap-part="keys-list"></div>
  <div class="cap-dialog-footer" data-align="start">
    <div class="cap-keys-foot">
      <label class="cap-switch"><input type="checkbox" role="switch" data-cap-part="single-keys" aria-describedby="comf-note" checked /><span>Single-key shortcuts</span><span class="cap-switch-state" aria-hidden="true">On</span></label>
      <p class="cap-keys-note" id="comf-note">Turn these off if they clash with a screen reader or speech input. It applies at once. Shortcuts with Ctrl or ⌘ keep working.</p>
    </div>
  </div>
  <button type="button" class="cap-btn cap-dialog-close" data-variant="quiet" data-icon-only data-cap-part="close" aria-label="Close"><svg viewBox="0 0 16 16" width="16" height="16" aria-hidden="true" focusable="false"><path d="M4 4l8 8M12 4l-8 8" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" /></svg></button>
</dialog>

API reference

Keys

PropTypeRequiredDoes
specstring | string[]Yes

ShortcutSheet

PropTypeRequiredDoes
openbooleanYes
onOpenChange(open: boolean) => voidYes

Functions

FunctionSignatureDoes
useShortcut(key: string | string[], run: (e: KeyboardEvent) => void, opts?: { label?: string | undefined; about?: string | undefined; group?: string | undefined; when?: (() => boolean) | undefined; }): voidRegisters a shortcut while the component is mounted. The latest run is always the one called, so passing a new function each render does not re-register.
isMac(): boolean
isSingleKey(spec: string): booleanA single-key shortcut is one a person can press by accident while typing or speaking: no Ctrl, Cmd or Alt in any step.
singleKeysOn(): boolean
singleKeysOff(): boolean
setSingleKeys(on: boolean, opts?: { remember?: boolean | undefined; }): voidTurns single-key shortcuts on or off, here and in every component. Remembered in this browser unless remember is false (a specimen, a test).
isImeEnter(e: Pick<KeyboardEvent, "key" | "isComposing" | "keyCode">): booleanTrue for an Enter that confirms an IME conversion (Japanese, Chinese, Korean input) and must not submit or act. isComposing covers Chrome and Firefox; keyCode 229 covers Safari, which fires compositionend before the confirming keydown and so reports isComposing false (WebKit bug 165004). Only meaningful behind an Enter check: a phone keyboard reports 229 for ordinary keys too. (Modern Web Guidance, ime-safe-enter-submit.)
isTyping(target: EventTarget | null): boolean
fire(s: Shortcut, e: KeyboardEvent): boolean
start(): voidInstalls the one listener and the "?" shortcut. Called by register(); safe to call again.
modifiedShortcutFor(e: KeyboardEvent): Shortcut | undefinedThe registered shortcut with Ctrl, Cmd or Alt that this key event matches, if any, and whether its when allows it now. For a surface open over the page (the sheet) that lets such a key through: the Portal's Ctrl K pressed in the help sheet closes the sheet and opens the command menu. Keys that match nothing (Ctrl C) are left alone.
stop(): voidRemoves the listener and every shortcut.
register(s: Shortcut): () => voidAdds a shortcut. Returns a function that removes it.
registerKey(s: Shortcut): () => voidAdds a shortcut without offering the "?" sheet, for a key a page has whether or not it lists its shortcuts (the site header's theme key). It is listed when something else on the page offers the sheet. The sheet is not part of a bundle that reaches the registry only through this: a classic /site.js inlines the sheet's lazy import, so a page with no other shortcut would carry it to list one key.
list(): Shortcut[]
grouped(): { group: string; items: Shortcut[]; }[]The registry by group, in the order each group first appears.
capName(cap: string): string | undefinedThe spoken name of a key cap drawn as a symbol (an arrow); undefined for a cap that reads as it is.
keyCaps(spec: string): string[]What a key spec looks like on a key cap, one string per step: "Mod+k" is ["Ctrl K"] (["⌘ K"] on a Mac), "g o" is ["g", "o"].
keysFragment(key: string | string[]): DocumentFragmentThe key caps of a shortcut as <kbd> elements: "g o" is two caps, several keys are joined with "or".
setSheetOpener(fn: (() => void) | null): void--------------------------------------------------------------------------------------- The sheet. Lets an app (the React wrapper) open its own sheet when "?" is pressed.
enhance(root?: ParentNode): () => voidWires a sheet written in markup and every [data-cap-keys-open] button under root, and starts the registry. Returns a function that detaches them.

Parts and data attributes

ClassIs
.cap-kbdthe root
.cap-kbd-groupa part
.cap-keys-aboutits own class
.cap-keys-bodyits own class
.cap-keys-footits own class
.cap-keys-groupits own class
.cap-keys-group-titleits own class
.cap-keys-listits own class
.cap-keys-noteits own class

Accessibility

KeyDoes
?Opens the sheet (a single key: off when single keys are off; the sheet is also a command and a button)
EscCloses the sheet; focus returns to what opened it
Space on the switchTurns single-key shortcuts on or off, at once
Ctrl K, Cmd K (any registered Ctrl or Cmd key) in the open sheetCloses the sheet and runs it
A registered keyRuns its command, unless focus is in a field or a dialog is open
g, then a second key within 1200 msRuns a two-key shortcut
  • The sheet is a native modal dialog, named by its title; Close, the corner icon button named "Close", has focus on open, so nothing changes by arriving.
  • The switch is a checkbox with role="switch" and a fixed label, "Single-key shortcuts"; the On or Off word beside it is aria-hidden because the switch states it. A note says why someone would turn it off.
  • Shortcuts are listed as a description list per group: the keys, then what they do.