useHotkeyRegistrations causes React setState-in-render warning with useHotkey

[OliverJAsh]

Description

When one component subscribes to hotkey registrations using useHotkeyRegistrations() and another component registers a hotkey using useHotkey(), React logs a warning:

Cannot update a component (`ShortcutsBar`) while rendering a different component (`HotkeyOwner`). To locate the bad setState() call inside `HotkeyOwner`, follow the stack trace as described in https://react.dev/link/setstate-in-render

This appears to happen because useHotkey() updates registration options during render after a hotkey has been registered, and useHotkeyRegistrations() subscribes another component to the same registration store.

Reproduction

Reduced repro repo:

https://github.com/OliverJAsh/tanstack-hotkeys-render-warning-repro

Steps:

git clone https://github.com/OliverJAsh/tanstack-hotkeys-render-warning-repro.git
cd tanstack-hotkeys-render-warning-repro
npm install
npm run dev

Open the page in a browser.

Expected Behavior

Using useHotkeyRegistrations() to render a shortcuts bar should not trigger React warnings when hotkeys are registered or updated.

Actual Behavior

React logs the setState-in-render warning during initial page load:

Cannot update a component (`ShortcutsBar`) while rendering a different component (`HotkeyOwner`).

Suspected Cause

In useHotkey, callback/options are synced during render:

if (registrationRef.current?.isActive) {
  registrationRef.current.callback = callback
  registrationRef.current.setOptions(optionsWithoutTarget)
}

setOptions(...) updates the global hotkey registration store. Since ShortcutsBar is subscribed through useHotkeyRegistrations(), React sees this as updating ShortcutsBar while rendering HotkeyOwner.

Environment

• @tanstack/react-hotkeys: 0.10.0
• React: latest / React 19
• Browser: Chromium
• Build tool: Vite

[krehwell]

I fix it by assign it as a memoize component instead

const HotkeyRegistrer = React.memo(
    ({ hotkey, action, ...options }) => {
        useHotkey(hotkey, action, options);
        return null;
    },
    (prev, next) => prev.hotkey === next.hotkey
);

[IanWorley]

I would not mind taking a look at this. I did some investigating and have possible fix with useEffect. As the store is getting updated while react is trying to render HotkeyOwner.

[volkandkaya]

I have this issue as well, have a <Shortcuts> where i list them.

[OffCrazyFreak]

Still happening on @tanstack/react-hotkeys@0.10.0 with @tanstack/hotkeys@0.8.0, React 19.2.3, Next 16.2.10.

A few things have changed since this was filed, in case it saves anyone the digging.

#141 is closed, not merged. @IanWorley opened it on 2026-07-19 with a fix that moved setOptions into an effect, plus a test asserting the notification order. It was closed a day later without review. main still has the original block, so nothing has shipped:

// Sync callback and options on EVERY render (outside useEffect)
if (registrationRef.current?.isActive) {
  registrationRef.current.callback = callback
  registrationRef.current.setOptions(optionsWithoutTarget)
}

useHotkeys (plural) has the same block, and #141 only touched the singular hook. The loop at the end of useHotkeys.ts:

if (handle?.isActive) {
  handle.callback = def.callback
  ...
  handle.setOptions(optionsWithoutTarget)
}

So anyone registering through the plural hook hits this as well, and would have kept hitting it even if #141 had landed. Worth covering both if someone picks this up again.

There is a second cause in the core package. setOptions in hotkey-manager.ts rebuilds the Map unconditionally:

setOptions: (newOptions: Partial<HotkeyOptions>) => {
  manager.registrations.setState((prev) => {
    const reg = prev.get(id)
    if (reg) {
      const next = new Map(prev)
      next.set(id, { ...reg, options: { ...reg.options, ...newOptions } })
      return next
    }
    return prev
  })
}

Nothing checks whether the options actually changed, so every render of every component holding a registration notifies every useHotkeyRegistrations subscriber even when the options are identical. Moving the call into an effect fixes the React warning on its own. A shallow comparison here would also drop the redundant notifications, which in our app is one per keystroke, because the component holding the shortcuts re-renders on every keypress in a form.

A workaround, if anyone needs one now. The React.memo wrapper above reduces how often the write fires but does not stop it. What worked for us was dropping useHotkeyRegistrations on the reading side and taking an unsubscribed snapshot during render:

function useHotkeyLegend() {
  const manager = getHotkeyManager()
  const [, forceUpdate] = useState(0)

  useEffect(() => {
    let queued: ReturnType<typeof setTimeout> | null = null

    function schedule() {
      if (queued !== null) return
      queued = setTimeout(() => {
        queued = null
        forceUpdate((n) => n + 1)
      }, 0)
    }

    const subscription = manager.registrations.subscribe(schedule)

    return () => {
      if (queued !== null) clearTimeout(queued)
      subscription.unsubscribe()
    }
  }, [manager])

  return Array.from(manager.registrations.state.values()).map(toHotkeyRegistrationView)
}

Our shortcut list always renders below the component that registers the shortcuts, so the render-phase write has already landed by the time React reaches it, and re-rendering the parent re-renders the list anyway. The deferred subscription is only there for registrations coming from somewhere that is not an ancestor. Fixing the reading side also sidesteps the singular and plural split.

[alexwestphal]

The warning escalates to a hard freeze if a single component both subscribes and registers. A shortcuts palette that also owns a hotkey (e.g. ? to toggle itself — close to the ShortcutPalette in useHotkeyRegistrations' own JSDoc) doesn't just warn, it enters an unrecoverable synchronous render loop: render-phase setOptions → store notification → useSyncExternalStore re-render → render-phase setOptions again, with no yield. React's "maximum update depth" guard never fires because the loop runs through the external store, not React state — the tab just locks. (@tanstack/react-hotkeys@0.10.0, @tanstack/hotkeys@0.8.0, React 19.2.)

Small note on the read side: useHotkeyRegistrations calls useSelector(manager.registrations, s => Array.from(s.values()).map(toHotkeyRegistrationView)) with no compare option, and the selector allocates a fresh array each call, so every store notification re-renders every subscriber regardless of what changed. An equality guard in setOptions makes this moot (no notification); failing that, { compare: shallow } here would help for genuine unrelated changes.

Workaround we landed on, for the both-in-one-component case: don't call useHotkeyRegistrations at all — snapshot getHotkeyManager().registrations.state once when the overlay opens. A help dialog is short-lived and shortcuts don't change while it's on screen, so a live subscription isn't needed.