TanStack / TanStack/hotkeys

useHotkeyRegistrations causes React setState-in-render warning with useHotkey

Open
#113 5 comments 5 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
TypeScript
Stars
719
Forks
47
Avg merge
5d 5h
Merged PRs (30d)
1

Description

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

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Reproduce the warning with the linked reduced repro using the listed npm commands. Start by reading the useHotkey and useHotkeyRegistrations implementations, focusing on registration updates during render and the shared store subscription. Done means the reproduction no longer logs the React setState-in-render warning when registrations are rendered or updated.

Written by the indexing model from the issue text.

Assessment

Tech stack
react, typescript
Domain
frontend
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
65/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.