formatForDisplay orders macOS modifiers differently from Apple HIG
Nobody has claimed this yet.
Assessment
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Newbie friendliness
- 68/100
- Issue type
- Bug
- Clarity
- Clearly specified
- Activity status
- Quiet
- Tech stack
- react, typescript
- Domain
- frontend
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.
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
- Dominant language
- TypeScript
- Stars
- 719
- Forks
- 47
- Avg merge
- 5d 5h
- Merged PRs (30d)
- 1
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.
More from TanStack/hotkeys
-
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 70/100
-
Difficulty 3/5 1-2 days Newbie friendliness 74/100
-
Difficulty 3/5 1-2 days Newbie friendliness 76/100
-
Difficulty 4/5 3-5 days Newbie friendliness 50/100
All issues in TanStack/hotkeys
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 84/100
Eynzof/Hermes-CN-Desktop#610 ·
-
bug clawsweeper:linked-pr-open clawsweeper:needs-live-repro clawsweeper:no-new-fix-pr impact:message-loss issue-rating: 🐚 platinum hermit P2 regression
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
-
enhancement
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
-
calcite-components needs triage refactor
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
Esri/calcite-design-system#15203 ·
-
Difficulty 1/5 Under an hour Newbie friendliness 78/100
fullcalendar/fullcalendar#8106 ·