formatForDisplay orders macOS modifiers differently from Apple HIG
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 719
- Forks
- 47
- Avg merge
- 5d 5h
- Merged PRs (30d)
- 1
Description
TanStack Hotkeys version
@tanstack/hotkeys v0.8.0
Framework/Library version
React, via @tanstack/react-hotkeys
Describe the bug and the steps to reproduce it
formatForDisplay currently formats multi-modifier shortcuts on macOS in the library's canonical modifier order.
For example:
formatForDisplay("Mod+Shift+S", { platform: "mac" })
currently returns:
⌘ ⇧ S
Apple's Human Interface Guidelines say custom keyboard shortcuts should list modifier keys in this order:
Control, Option, Shift, Command
So on macOS I would expect:
⇧ ⌘ S
Similarly, combinations involving Option/Shift/Command should be displayed in Apple HIG order, while keeping the existing canonical order for parsing/normalization if needed.
Reference:
https://developer.apple.com/design/human-interface-guidelines/keyboards#Custom-keyboard-shortcuts
Minimal reproduction
No sandbox needed; this reproduces with the formatter directly:
import { formatForDisplay } from "@tanstack/hotkeys";
formatForDisplay("Mod+Shift+S", { platform: "mac" });
// actual: "⌘ ⇧ S"
// expected: "⇧ ⌘ S"
Suggested fix
Keep parser/normalization order as-is, but make macOS display formatting sort modifier tokens as:
Control → Option → Shift → Command
Do you intend to try to help solve this bug with your own PR?
Maybe, I'll investigate and start debugging
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start at the formatForDisplay entry point in @tanstack/hotkeys and trace how macOS modifier tokens are ordered for display without changing parser or normalization ordering. Verify combinations involving Control, Option, Shift, and Command, including Mod+Shift+S, and confirm the output follows Apple HIG order.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- react, typescript
- Domain
- frontend
- Issue type
- Bug
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 68/100