Getting started

Install

pnpm

pnpm add react-remap

npm

npm install react-remap

yarn

yarn add react-remap

Beta

react-remap is in beta and not yet published to npm — it currently lives inside the remap monorepo. This page describes the API as it will ship.

Wrap your app

import { RemapProvider } from "react-remap";

export function Root() {
  return (
    <RemapProvider>
      <App />
    </RemapProvider>
  );
}

<RemapProvider> mounts a single window key listener and the built-in ⌘, overlay. That's the entire setup.

Register shortcuts

import { useHotkey } from "react-remap";

function Editor() {
  useHotkey("editor.save", "mod+s", () => save(), {
    description: "Save document", // shown in the overlay
    group: "Editor",              // overlay section heading
  });
  // …
}

The keys argument is only the default. If the user remapped the action, their combo wins automatically — you never read or write the user's config yourself.

Use area.verb ids ("editor.save", "nav.search"). Ids are the stable identity of an action across releases; the combo can change, the id shouldn't.

Let users remap

Nothing to do — users press ⌘, (Ctrl, on Windows/Linux), click an action, and press new keys. Changes apply instantly and persist per app.

To open the overlay from a menu item:

import { useRemap } from "react-remap";

const { openSettings } = useRemap();
<button onClick={openSettings}>Keyboard shortcuts…</button>;

Show live hints

Render keycap hints that update when the user remaps:

import { useRemap, displayParts } from "react-remap";

function SaveHint() {
  const { keysFor } = useRemap();
  return (
    <span>
      {displayParts(keysFor("editor.save") ?? "mod+s").map((p, i) => (
        <kbd key={i}>{p}</kbd>
      ))}
    </span>
  );
}

Next

• Combo syntax — what strings like "mod+shift+k" mean
• Storage & sync — where customizations live
• API reference — every prop and function