Fix KeybindingHint key display on non-MacOS/Windows platforms by jonrohan · Pull Request #7908 · primer/react

jonrohan · 2026-05-29T22:30:10Z

Here's a preview of all the modifier keys on different platforms https://primer-11d74e8128-13348165.drafts.github.io/storybook/?path=/story/experimental-components-keybindinghint-features--platforms

KeybindingHint previously only distinguished between MacOS and "not MacOS" when displaying the Meta, Alt, and Mod keys. As a result, the Meta key was rendered as Win (Windows key) on Linux, Android, and other platforms where that key does not exist.

This change introduces a three-way platform detection (mac / windows / other) so keys are displayed correctly per platform.

Changelog

New

Added an SSR-safe usePlatform() hook (internal to KeybindingHint) that returns 'mac' | 'windows' | 'other'. Apple platforms (macOS and iOS/iPadOS) map to 'mac'.

Changed

KeybindingHint now resolves platform-specific keys based on the detected platform:
- Meta: ⌘/Command on Apple, Win/Windows on Windows, Meta on all other platforms.
- Alt: ⌥/Option on Apple, Alt elsewhere.
- Mod: ⌘/Command on Apple, ⌃/Control elsewhere.
getAccessibleKeybindingHintString remains backward compatible — it still accepts the previous boolean argument (true → 'mac', false → 'other') in addition to a Platform value.

Removed

N/A

Rollout strategy

Patch release

Testing & Reviewing

Unit tests were added covering Meta, Alt, and Mod rendering across all three platform categories. Existing KeybindingHint, Tooltip, and TreeView tests pass.

Merge checklist

changeset-bot · 2026-05-29T22:30:16Z

🦋 Changeset detected

Latest commit: a1789a3

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@primer/react	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

github-actions · 2026-05-29T22:30:41Z

⚠️ Action required

👋 Hi, this pull request contains changes to the source code that github/github-ui depends on. If you are GitHub staff, test these changes with github/github-ui using the integration workflow. Check the integration testing docs for step-by-step instructions. Or, apply the integration-tests: skipped manually label to skip these checks.

To publish a canary release for integration testing, apply the Canary Release label to this PR.

Copilot

Pull request overview

This PR updates KeybindingHint platform handling so modifier keys are displayed appropriately on Apple, Windows, and other platforms, addressing Linux/Android Meta key labeling.

Changes:

Added internal tri-state platform detection and platform override support for Storybook previews.
Updated KeybindingHint, TooltipV2, and TreeView to use platform-aware key naming.
Added accessible-string tests and a Storybook matrix for platform-specific modifier rendering.

Show a summary per file

File	Description
`packages/react/src/TreeView/TreeView.tsx`	Uses the new platform hook for TreeView shortcut labels.
`packages/react/src/TooltipV2/Tooltip.tsx`	Uses platform-aware accessible shortcut descriptions.
`packages/react/src/KeybindingHint/platform.ts`	Adds platform detection and override context.
`packages/react/src/KeybindingHint/KeybindingHint.tsx`	Updates accessible helper to accept platform values.
`packages/react/src/KeybindingHint/KeybindingHint.test.tsx`	Adds accessible-name coverage for platform-specific keys.
`packages/react/src/KeybindingHint/KeybindingHint.features.stories.tsx`	Adds a platform comparison Storybook story.
`packages/react/src/KeybindingHint/KeybindingHint.features.stories.module.css`	Styles the new platform comparison table.
`packages/react/src/KeybindingHint/key-names.ts`	Implements platform-specific key-name mappings.
`packages/react/src/KeybindingHint/components/Sequence.tsx`	Threads platform values through accessible sequence strings.
`packages/react/src/KeybindingHint/components/Key.tsx`	Renders keys using detected platform mappings.
`packages/react/src/KeybindingHint/components/Chord.tsx`	Threads platform values through accessible chord strings.
`.changeset/keybinding-hint-platform-keys.md`	Adds a patch changeset for the behavior fix.

Copilot's findings

Files reviewed: 12/12 changed files
Comments generated: 1

 shift: '⇧',
- meta: isMacOS ? '⌘' : 'Win',
- mod: isMacOS ? '⌘' : '⌃',
+ meta: platform === 'mac' ? '⌘' : platform === 'windows' ? 'Win' : 'Meta',


github-actions · 2026-05-29T23:18:26Z

Uh oh! @jonrohan, at least one image you shared is missing helpful alt text. Check your pull request body to fix the following violations:

Images should have meaningful alternative text (alt text) at line 5
Images should have meaningful alternative text (alt text) at line 7

Alt text is an invisible description that helps screen readers describe images to blind or low-vision users. If you are using markdown to display images, add your alt text inside the brackets of the markdown image.

Learn more about alt text at Basic writing and formatting syntax: images on GitHub Docs.

🤖 Beep boop! This comment was added automatically by github/accessibility-alt-text-bot.

primer-integration · 2026-05-29T23:43:10Z

👋 Hi from github/github-ui! Your integration PR is ready: https://github.com/github/github-ui/pull/21980

primer-integration · 2026-05-30T00:04:27Z

Integration test results from github/github-ui:

CI Passed
VRT Running
Projects Passed

iansan5653 · 2026-06-01T14:53:43Z

useIsMacOS is a common, shared utility hook. Should usePlatform live in the same place? Or maybe we should just update that hook to be more powerful? Seems like this could be useful for other components.

iansan5653 · 2026-06-01T14:55:10Z

+ * `'other'`.
 */
-export const getAccessibleKeybindingHintString = accessibleSequenceString
+export const getAccessibleKeybindingHintString = (sequence: string, platform: Platform | boolean) =>


A followup task after release should be to update consumers in github/github to use the new Platform type instead of boolean

TylerJDev

LGTM! +1 to Ian's comments, though approving ahead of time.

…pple'

Fix KeybindingHint key display on non-MacOS/Windows platforms
7a7da00

github-actionsBot added staff Author is a staff member integration-tests: recommended This change needs to be tested for breaking changes. See https://arc.net/l/quote/tdmpakpm labels May 29, 2026

jonrohan deployed to github-pages May 29, 2026 22:41 — with GitHub Actions View deployment

github-actionsBottemporarily deployed to storybook-preview-7908 May 29, 2026 22:42 Inactive

Add story demonstrating modifier keys across platforms
4cb7c0e

jonrohan marked this pull request as ready for review May 29, 2026 23:05

jonrohan requested a review from a team as a code owner May 29, 2026 23:05

jonrohan requested review from TylerJDev and Copilot May 29, 2026 23:05

Copilotstarted reviewing on behalf of jonrohan May 29, 2026 23:06 View session

CopilotAI reviewed May 29, 2026
View reviewed changes

Comment threadpackages/react/src/KeybindingHint/key-names.ts Outdated
shift: '⇧',
meta: isMacOS ? '⌘' : 'Win',
mod: isMacOS ? '⌘' : '⌃',
meta: platform === 'mac' ? '⌘' : platform === 'windows' ? 'Win' : 'Meta',

jonrohan deployed to github-pages May 29, 2026 23:16 — with GitHub Actions View deployment

github-actionsBottemporarily deployed to storybook-preview-7908 May 29, 2026 23:16 Inactive

jonrohan requested a review from iansan5653 May 29, 2026 23:18

jonrohan added the Canary Release Apply this label when you want CI to create a canary release of the current PR label May 29, 2026

iansan5653 approved these changes Jun 1, 2026
View reviewed changes

TylerJDev approved these changes Jun 1, 2026
View reviewed changes

refactor(KeybindingHint): update platform identifier from 'mac' to 'a…
9dd3b19
…pple'

jonrohan enabled auto-merge June 1, 2026 21:06

jonrohan deployed to github-pages June 1, 2026 21:16 — with GitHub Actions View deployment

github-actionsBottemporarily deployed to storybook-preview-7908 June 1, 2026 21:17 Inactive

Merge branch 'main' into fix-keybinding-hint-platform-keys
a1789a3

jonrohan added the integration-tests: skipped manually Changes in this PR do not require an integration test label Jun 1, 2026

jonrohan added this pull request to the merge queue Jun 1, 2026

jonrohan deployed to github-pages June 1, 2026 21:27 — with GitHub Actions View deployment

github-actionsBottemporarily deployed to storybook-preview-7908 June 1, 2026 21:27 Inactive

Merged via the queue into main with commit e9a2254Jun 1, 2026
59 of 60 checks passed

jonrohan deleted the fix-keybinding-hint-platform-keys branch June 1, 2026 21:34

primerBot mentioned this pull request Jun 1, 2026
Release tracking #7907
Merged

Navigation Menu

Uh oh!

Fix KeybindingHint key display on non-MacOS/Windows platforms - #7908

Fix KeybindingHint key display on non-MacOS/Windows platforms#7908
jonrohan merged 4 commits into
mainfrom
fix-keybinding-hint-platform-keys

jonrohan commented May 29, 2026•
edited
Loading

Uh oh!

changeset-botBot commented May 29, 2026•
edited
Loading

Uh oh!

github-actionsBot commented May 29, 2026

Uh oh!

CopilotAI left a comment

Uh oh!

github-actionsBot commented May 29, 2026•
edited
Loading

Uh oh!

primer-integrationBot commented May 29, 2026

Uh oh!

primer-integrationBot commented May 30, 2026

Uh oh!

iansan5653Jun 1, 2026

Uh oh!

iansan5653Jun 1, 2026

Uh oh!

Uh oh!

TylerJDev left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

jonrohan commented May 29, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changelog

New

Changed

Removed

Rollout strategy

Testing & Reviewing

Merge checklist

Uh oh!

changeset-botBot commented May 29, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

github-actionsBot commented May 29, 2026

⚠️ Action required

Uh oh!

CopilotAI left a comment

Choose a reason for hiding this comment

Pull request overview

Copilot's findings

Uh oh!

github-actionsBot commented May 29, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

primer-integrationBot commented May 29, 2026

Uh oh!

primer-integrationBot commented May 30, 2026

Uh oh!

iansan5653Jun 1, 2026

Choose a reason for hiding this comment

Uh oh!

iansan5653Jun 1, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

TylerJDev left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

jonrohan commented May 29, 2026•
edited
Loading

changeset-botBot commented May 29, 2026•
edited
Loading

github-actionsBot commented May 29, 2026•
edited
Loading