API reference

Everything react-remap exports.

<RemapProvider>

Mounts the key listener, the config store, and the ⌘, overlay. One per app.

Prop	Type	Default	Purpose
appId	string	location.hostname	Stable key for saved configs
shortcuts	Record<string, ShortcutDef>	—	Register actions up front (pairs with remap:action events)
settingsHotkey	string | false	"mod+,"	Combo opening the overlay; false disables
serverUrl	string | null	remap cloud	Sync server base URL; null disables remote sync
agentPort	number | null	53137	Device-agent probe port; null disables

useHotkey(id, keys, handler, options?)

Registers a user-remappable shortcut for the lifetime of the component.

useHotkey(
  id: string,                       // stable action id, e.g. "editor.save"
  keys: string,                     // DEFAULT combo — user overrides win
  handler: (e: KeyboardEvent) => void,
  options?: {
    description?: string;          // overlay label
    group?: string;                // overlay section
    enableOnFormTags?: boolean;    // fire inside inputs (default false)
    preventDefault?: boolean;      // default true
    enabled?: boolean;             // false = registered but inert
  }
): void

useRemap()

Programmatic access to the store. All values are reactive.

const {
  appId,          // resolved app id
  shortcuts,      // { [id]: def & { effectiveKeys, customized } }
  overrides,      // { local, device, remote } raw layers
  keysFor,        // (id) => string | null  (null = disabled)
  setOverride,    // (id, keys | null) => void — null disables
  clearOverride,  // (id) => void — back to default
  resetAll,       // () => void
  openSettings,   // () => void — open the ⌘, overlay
  closeSettings,  // () => void
} = useRemap();

<RemapOverlay />

The overlay component itself. Rendered automatically by the provider — exported only for advanced cases (custom mounting). Inline-styled, portal to document.body, follows prefers-color-scheme.

Key utilities

parseCombo("mod+shift+k")     // { meta, ctrl, alt, shift, key } (platform-resolved)
eventMatches(event, "mod+s")  // boolean — does this KeyboardEvent match?
comboFromEvent(event)         // canonical combo string, or null for bare modifiers
displayParts("mod+shift+k")   // ["⌘","⇧","K"] / ["Ctrl","Shift","K"]
isMac                         // boolean

Sync token helpers

getSyncToken(): string | null       // read the stored remap account token
setSyncToken(token: string | null)  // store/clear it (localStorage "remap:sync-token")

Window events

Every fired shortcut also dispatches a DOM event — an alternative to handlers for actions living outside React:

window.addEventListener("remap:action", (e) => {
  const { id, event } = (e as CustomEvent).detail;
});

Types

ShortcutDef, Overrides, RemapConfig, ParsedCombo are exported for TypeScript consumers.

Server sync API (HTTP)

Used by the library when a sync token is present; also usable directly.

Route	Auth	Body / response
GET /api/sync/config/:appId	Authorization: Bearer rmp_…	{ appId, overrides }
PUT /api/sync/config/:appId	Authorization: Bearer rmp_…	{ overrides } → { appId, overrides }

overrides is { [shortcutId]: comboString | null } — null means disabled. Tokens come from the dashboard.