use-shortcut

v2.4.0

@remcostoeten/use-shortcut

Keyboard shortcuts without the ceremony.

A typed React shortcut builder for key combinations, sequences, scopes, recording, and debug hooks, without scattering keyboard listeners through every component.

Documentation npm package Source

What it replaces

Keyboard listeners get messy once shortcuts have scope.

Use it when shortcuts are part of product behavior, not a one-off event listener: command palettes, editors, complex dialogs, data-heavy interfaces, and apps with keyboard-first flows.

Fluent builder for combinations, pre-bound strings, sequences, modifiers, priorities, and conflict checks.
Scopes, guards, and input handling let shortcuts behave correctly in layered application UI.
Typed maps, recording mode, structured debug events, and attempt inspection support larger shortcut systems.

Quick start

Start with one small integration.

$ npm install @remcostoeten/use-shortcut

components/command-menu.tsxtsx

1import { useShortcut } from '@remcostoeten/use-shortcut/react'23export function CommandMenu() {4  const $ = useShortcut()56  $.mod.key('k').on(() => openPalette(), {7    preventDefault: true8  })910  $.key('escape').on(() => closePalette())11}

Integration shape

A small path from install to product behavior.

01
Create builder
Call useShortcut once inside feature component.
02
Describe intent
Bind combinations or sequences close to feature behavior.
03
Control scope
Enable only where shortcut should own keyboard input.

API examples

Start with one call. Add the pieces when you need them.

1. Bind one key

Start with one shortcut next to the feature it controls.

components/command-menu.tsxtsx

1const $ = useShortcut()23$.key('escape').on(() => closePalette())

2. Add a modifier

Build combinations without writing platform-specific listeners.

components/command-menu.tsxtsx

1const $ = useShortcut()23$.mod.key('k').on(() => openPalette())

3. Add scope and options

Keep the shortcut local when the interface has multiple active layers.

components/command-menu.tsxtsx

1$.mod.key('k').on(() => openPalette(), {2  scope: 'command-menu',3  preventDefault: true4})

useShortcut(): Returns chainable shortcut builder.
$.bind(): Registers a shortcut from a string or config value.
$.key().then(): Builds ordered keyboard sequences.

useShortcut()

const $ = useShortcut(options?)

options.scopeOptional default scope for shortcuts created by this builder.
options.enabledOptional switch for disabling the builder without unmounting the component.

$.key().on()

$.mod.key('k').on(handler, options?)

handlerRuns when the key combination matches.
options.preventDefaultPrevent the browser’s default action for the matching key.
options.scopeLimit the shortcut to an active scope such as command-menu or editor.

$.key().then()

$.key('g').then('d').on(openDashboard)

then(key)Append the next key in an ordered sequence.
on(handler)Run the handler after the complete sequence matches.

Keyboard listeners get messy once shortcuts have scope.

Use it when shortcuts are part of product behavior, not a one-off event listener: command palettes, editors, complex dialogs, data-heavy interfaces, and apps with keyboard-first flows.

Fluent builder for combinations, pre-bound strings, sequences, modifiers, priorities, and conflict checks.

Scopes, guards, and input handling let shortcuts behave correctly in layered application UI.

Typed maps, recording mode, structured debug events, and attempt inspection support larger shortcut systems.

Start with one small integration.

$ npm install @remcostoeten/use-shortcut

components/command-menu.tsxtsx

1import { useShortcut } from '@remcostoeten/use-shortcut/react'23export function CommandMenu() {4  const $ = useShortcut()56  $.mod.key('k').on(() => openPalette(), {7    preventDefault: true8  })910  $.key('escape').on(() => closePalette())11}

Start with one call. Add the pieces when you need them.

1. Bind one key

Start with one shortcut next to the feature it controls.

components/command-menu.tsxtsx

1const $ = useShortcut()23$.key('escape').on(() => closePalette())

2. Add a modifier

Build combinations without writing platform-specific listeners.

components/command-menu.tsxtsx

1const $ = useShortcut()23$.mod.key('k').on(() => openPalette())

3. Add scope and options

Keep the shortcut local when the interface has multiple active layers.

components/command-menu.tsxtsx

1$.mod.key('k').on(() => openPalette(), {2  scope: 'command-menu',3  preventDefault: true4})

useShortcut()

Returns chainable shortcut builder.

$.bind()

Registers a shortcut from a string or config value.

$.key().then()

Builds ordered keyboard sequences.

useShortcut()

const $ = useShortcut(options?)

options.scopeOptional default scope for shortcuts created by this builder.
options.enabledOptional switch for disabling the builder without unmounting the component.

$.key().on()

$.mod.key('k').on(handler, options?)

handlerRuns when the key combination matches.
options.preventDefaultPrevent the browser’s default action for the matching key.
options.scopeLimit the shortcut to an active scope such as command-menu or editor.

$.key().then()

$.key('g').then('d').on(openDashboard)

then(key)Append the next key in an ordered sequence.
on(handler)Run the handler after the complete sequence matches.

Keyboard listeners get messy once shortcuts have scope.

Start with one small integration.

A small path from install to product behavior.

Create builder

Describe intent

Control scope

Start with one call. Add the pieces when you need them.

1. Bind one key

2. Add a modifier

3. Add scope and options

useShortcut()

$.key().on()

$.key().then()

Keyboard listeners get messy once shortcuts have scope.

Start with one small integration.

A small path from install to product behavior.

Create builder

Describe intent

Control scope

Start with one call. Add the pieces when you need them.

1. Bind one key

2. Add a modifier

3. Add scope and options

useShortcut()

$.key().on()

$.key().then()