TanStack · IanWorley · Jul 17, 2026 · Jul 18, 2026
diff --git a/docs/framework/lit/guides/formatting-display.md b/docs/framework/lit/guides/formatting-display.md
@@ -14,7 +14,7 @@ import { formatForDisplay } from '@tanstack/lit-hotkeys'
 
 // On macOS (symbols separated by spaces):
 formatForDisplay('Mod+S')         // "⌘ S"
-formatForDisplay('Mod+Shift+Z')   // "⌘ ⇧ Z"
+formatForDisplay('Mod+Shift+Z')   // "⇧ ⌘ Z"
 formatForDisplay('Control+Alt+D') // "⌃ ⌥ D"
 
 // On Windows/Linux:
@@ -32,7 +32,7 @@ formatForDisplay('Mod+S', {
 })
 ```
 
-On macOS, modifier **order** matches canonical normalization (same as `formatWithLabels`), and symbols are joined with **spaces** (e.g., `⌘ ⇧ Z`). On Windows and Linux, modifiers are joined with `+` (e.g., `Ctrl+Shift+Z`).
+On macOS, modifier **order** follows [Apple's Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/keyboards) (Control → Option → Shift → Command, same as `formatWithLabels`), and symbols are joined with **spaces** (e.g., `⇧ ⌘ Z`). On Windows and Linux, modifiers are joined with `+` (e.g., `Ctrl+Shift+Z`).
 
 `platform` is used for both normalization and display. If you need to show the same [`ParsedHotkey`](../../../reference/interfaces/ParsedHotkey.md) under several platforms, first serialize with the platform it was parsed with, then format for each display platform:
 
@@ -57,14 +57,14 @@ import { formatWithLabels } from '@tanstack/lit-hotkeys'
 
 // On macOS:
 formatWithLabels('Mod+S', { platform: 'mac' }) // "Cmd+S"
-formatWithLabels('Mod+Shift+Z', { platform: 'mac' }) // "Cmd+Shift+Z"
+formatWithLabels('Mod+Shift+Z', { platform: 'mac' }) // "Shift+Cmd+Z"
 
 // On Windows/Linux:
 formatWithLabels('Mod+S', { platform: 'windows' }) // "Ctrl+S"
 formatWithLabels('Mod+Shift+Z', { platform: 'windows' }) // "Ctrl+Shift+Z"
 ```
 
-Modifier order matches canonical normalization from the core package (e.g. `Mod` first, then `Shift`, then the key).
+On Windows and Linux, modifier order matches canonical normalization from the core package (e.g. `Mod` first, then `Shift`, then the key). On macOS, modifiers follow Apple's Human Interface Guidelines order.
 
 ## Using Formatted Hotkeys in Lit
 
@@ -87,7 +87,7 @@ class ShortcutBadge extends LitElement {
 Usage:
 ```html
 <shortcut-badge hotkey="Mod+S"></shortcut-badge>        <!-- ⌘ S (Mac) or Ctrl+S (Windows) -->
-<shortcut-badge hotkey="Mod+Shift+P"></shortcut-badge>  <!-- ⌘ ⇧ P (Mac) or Ctrl+Shift+P (Windows) -->
+<shortcut-badge hotkey="Mod+Shift+P"></shortcut-badge>  <!-- ⇧ ⌘ P (Mac) or Ctrl+Shift+P (Windows) -->
 ```
 
 ### Menu Items with Hotkeys
@@ -180,14 +180,24 @@ class CommandPaletteItem extends LitElement {
 
 ## Platform Symbols Reference
 
-On macOS, modifiers are displayed as symbols:
+On macOS, modifiers are displayed as symbols, and ordered per [Apple's Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/keyboards):
+
+| Modifier | Mac Symbol |
+|----------|-----------|
+| Control | `⌃` |
+| Option | `⌥` |
+| Shift | `⇧` |
+| Meta (Cmd) | `⌘` |
+
+On Windows and Linux, modifiers are displayed as text labels:
+
+| Modifier | Windows Label | Linux Label |
+|----------|---------------|-------------|
+| Meta | `Win` | `Super` |
+| Control | `Ctrl` | `Ctrl` |
+| Alt/Option | `Alt` | `Alt` |
+| Shift | `Shift` | `Shift` |
 
-| Modifier | Mac Symbol | Windows/Linux Label |
-|----------|-----------|-------------------|
-| Meta (Cmd) | `⌘` | `Win` / `Super` |
-| Control | `⌃` | `Ctrl` |
-| Alt/Option | `⌥` | `Alt` |
-| Shift | `⇧` | `Shift` |
 
 Special keys also have display symbols:
 

diff --git a/docs/framework/preact/guides/formatting-display.md b/docs/framework/preact/guides/formatting-display.md
@@ -14,7 +14,7 @@ import { formatForDisplay } from '@tanstack/preact-hotkeys'
 
 // On macOS (symbols separated by spaces):
 formatForDisplay('Mod+S')         // "⌘ S"
-formatForDisplay('Mod+Shift+Z')   // "⌘ ⇧ Z"
+formatForDisplay('Mod+Shift+Z')   // "⇧ ⌘ Z"
 formatForDisplay('Control+Alt+D') // "⌃ ⌥ D"
 
 // On Windows/Linux:
@@ -32,7 +32,7 @@ formatForDisplay('Mod+S', {
 })
 ```
 
-On macOS, modifier order matches canonical normalization (same as `formatWithLabels`), and symbols are joined with **spaces** (e.g., `⌘ ⇧ Z`). On Windows and Linux, modifiers are joined with `+` (e.g., `Ctrl+Shift+Z`).
+On macOS, modifier order follows [Apple's Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/keyboards) (Control → Option → Shift → Command, same as `formatWithLabels`), and symbols are joined with **spaces** (e.g., `⇧ ⌘ Z`). On Windows and Linux, modifiers are joined with `+` (e.g., `Ctrl+Shift+Z`).
 
 ## `formatWithLabels`
 
@@ -43,14 +43,14 @@ import { formatWithLabels } from '@tanstack/preact-hotkeys'
 
 // On macOS:
 formatWithLabels('Mod+S', { platform: 'mac' }) // "Cmd+S"
-formatWithLabels('Mod+Shift+Z', { platform: 'mac' }) // "Cmd+Shift+Z"
+formatWithLabels('Mod+Shift+Z', { platform: 'mac' }) // "Shift+Cmd+Z"
 
 // On Windows/Linux:
 formatWithLabels('Mod+S', { platform: 'windows' }) // "Ctrl+S"
 formatWithLabels('Mod+Shift+Z', { platform: 'windows' }) // "Ctrl+Shift+Z"
 ```
 
-Modifier order matches canonical normalization from the core package.
+On Windows and Linux, modifier order matches canonical normalization from the core package. On macOS, modifiers follow Apple's Human Interface Guidelines order.
 
 ## Using Formatted Hotkeys in Preact
 
@@ -65,7 +65,7 @@ function ShortcutBadge({ hotkey }: { hotkey: string }) {
 
 // Usage
 <ShortcutBadge hotkey="Mod+S" />      // Renders: ⌘ S (Mac) or Ctrl+S (Windows)
-<ShortcutBadge hotkey="Mod+Shift+P" /> // Renders: ⌘ ⇧ P (Mac) or Ctrl+Shift+P (Windows)
+<ShortcutBadge hotkey="Mod+Shift+P" /> // Renders: ⇧ ⌘ P (Mac) or Ctrl+Shift+P (Windows)
 ```
 
 ### Menu Items with Hotkeys
@@ -125,14 +125,23 @@ function CommandPaletteItem({ command }: { command: Command }) {
 
 ## Platform Symbols Reference
 
-On macOS, modifiers are displayed as symbols:
+On macOS, modifiers are displayed as symbols, and ordered per [Apple's Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/keyboards):
 
-| Modifier | Mac Symbol | Windows/Linux Label |
-|----------|-----------|-------------------|
-| Meta (Cmd) | `⌘` | `Win` / `Super` |
-| Control | `⌃` | `Ctrl` |
-| Alt/Option | `⌥` | `Alt` |
-| Shift | `⇧` | `Shift` |
+| Modifier | Mac Symbol |
+|----------|-----------|
+| Control | `⌃` |
+| Option | `⌥` |
+| Shift | `⇧` |
+| Meta (Cmd) | `⌘` |
+
+On Windows and Linux, modifiers are displayed as text labels:
+
+| Modifier | Windows Label | Linux Label |
+|----------|---------------|-------------|
+| Meta | `Win` | `Super` |
+| Control | `Ctrl` | `Ctrl` |
+| Alt/Option | `Alt` | `Alt` |
+| Shift | `Shift` | `Shift` |
 
 Special keys also have display symbols:
 

diff --git a/docs/framework/react/guides/formatting-display.md b/docs/framework/react/guides/formatting-display.md
@@ -14,7 +14,7 @@ import { formatForDisplay } from '@tanstack/react-hotkeys'
 
 // On macOS (symbols separated by spaces):
 formatForDisplay('Mod+S')         // "⌘ S"
-formatForDisplay('Mod+Shift+Z')   // "⌘ ⇧ Z"
+formatForDisplay('Mod+Shift+Z')   // "⇧ ⌘ Z"
 formatForDisplay('Control+Alt+D') // "⌃ ⌥ D"
 
 // On Windows/Linux:
@@ -32,7 +32,7 @@ formatForDisplay('Mod+S', {
 })
 ```
 
-On macOS, modifier **order** matches canonical normalization (same as `formatWithLabels`), and symbols are joined with **spaces** (e.g., `⌘ ⇧ Z`). On Windows and Linux, modifiers are joined with `+` (e.g., `Ctrl+Shift+Z`).
+On macOS, modifier **order** follows [Apple's Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/keyboards) (Control → Option → Shift → Command, same as `formatWithLabels`), and symbols are joined with **spaces** (e.g., `⇧ ⌘ Z`). On Windows and Linux, modifiers are joined with `+` (e.g., `Ctrl+Shift+Z`).
 
 `platform` is used for both normalization and display. If you need to show the same [`ParsedHotkey`](../../../reference/interfaces/ParsedHotkey.md) under several platforms, first serialize with the platform it was parsed with, then format for each display platform:
 
@@ -57,14 +57,14 @@ import { formatWithLabels } from '@tanstack/react-hotkeys'
 
 // On macOS:
 formatWithLabels('Mod+S', { platform: 'mac' }) // "Cmd+S"
-formatWithLabels('Mod+Shift+Z', { platform: 'mac' }) // "Cmd+Shift+Z"
+formatWithLabels('Mod+Shift+Z', { platform: 'mac' }) // "Shift+Cmd+Z"
 
 // On Windows/Linux:
 formatWithLabels('Mod+S', { platform: 'windows' }) // "Ctrl+S"
 formatWithLabels('Mod+Shift+Z', { platform: 'windows' }) // "Ctrl+Shift+Z"
 ```
 
-Modifier order matches canonical normalization from the core package (e.g. `Mod` first, then `Shift`, then the key).
+On Windows and Linux, modifier order matches canonical normalization from the core package (e.g. `Mod` first, then `Shift`, then the key). On macOS, modifiers follow Apple's Human Interface Guidelines order.
 
 ## Using Formatted Hotkeys in React
 
@@ -79,7 +79,7 @@ function ShortcutBadge({ hotkey }: { hotkey: string }) {
 
 // Usage
 <ShortcutBadge hotkey="Mod+S" />      // Renders: ⌘ S (Mac) or Ctrl+S (Windows)
-<ShortcutBadge hotkey="Mod+Shift+P" /> // Renders: ⌘ ⇧ P (Mac) or Ctrl+Shift+P (Windows)
+<ShortcutBadge hotkey="Mod+Shift+P" /> // Renders: ⇧ ⌘ P (Mac) or Ctrl+Shift+P (Windows)
 ```
 
 ### Menu Items with Hotkeys
@@ -139,14 +139,23 @@ function CommandPaletteItem({ command }: { command: Command }) {
 
 ## Platform Symbols Reference
 
-On macOS, modifiers are displayed as symbols:
+On macOS, modifiers are displayed as symbols, and ordered per [Apple's Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/keyboards):
 
-| Modifier | Mac Symbol | Windows/Linux Label |
-|----------|-----------|-------------------|
-| Meta (Cmd) | `⌘` | `Win` / `Super` |
-| Control | `⌃` | `Ctrl` |
-| Alt/Option | `⌥` | `Alt` |
-| Shift | `⇧` | `Shift` |
+| Modifier | Mac Symbol |
+|----------|-----------|
+| Control | `⌃` |
+| Option | `⌥` |
+| Shift | `⇧` |
+| Meta (Cmd) | `⌘` |
+
+On Windows and Linux, modifiers are displayed as text labels:
+
+| Modifier | Windows Label | Linux Label |
+|----------|---------------|-------------|
+| Meta | `Win` | `Super` |
+| Control | `Ctrl` | `Ctrl` |
+| Alt/Option | `Alt` | `Alt` |
+| Shift | `Shift` | `Shift` |
 
 Special keys also have display symbols:
 

diff --git a/docs/framework/solid/guides/formatting-display.md b/docs/framework/solid/guides/formatting-display.md
@@ -14,7 +14,7 @@ import { formatForDisplay } from '@tanstack/solid-hotkeys'
 
 // On macOS (symbols separated by spaces):
 formatForDisplay('Mod+S')         // "⌘ S"
-formatForDisplay('Mod+Shift+Z')   // "⌘ ⇧ Z"
+formatForDisplay('Mod+Shift+Z')   // "⇧ ⌘ Z"
 formatForDisplay('Control+Alt+D') // "⌃ ⌥ D"
 
 // On Windows/Linux:
@@ -32,7 +32,7 @@ formatForDisplay('Mod+S', {
 })
 ```
 
-On macOS, modifier order matches canonical normalization (same as `formatWithLabels`), with **spaces** between symbol segments.
+On macOS, modifier order follows [Apple's Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/keyboards) (Control → Option → Shift → Command, same as `formatWithLabels`), with **spaces** between symbol segments.
 
 ## `formatWithLabels`
 
@@ -43,7 +43,7 @@ import { formatWithLabels } from '@tanstack/solid-hotkeys'
 
 formatWithLabels('Mod+S', { platform: 'mac' }) // "Cmd+S"
 formatWithLabels('Mod+S', { platform: 'windows' }) // "Ctrl+S"
-formatWithLabels('Mod+Shift+Z', { platform: 'mac' }) // "Cmd+Shift+Z"
+formatWithLabels('Mod+Shift+Z', { platform: 'mac' }) // "Shift+Cmd+Z"
 formatWithLabels('Mod+Shift+Z', { platform: 'windows' }) // "Ctrl+Shift+Z"
 ```
 
@@ -107,12 +107,23 @@ function CommandPaletteItem(props: { command: Command }) {
 
 ## Platform Symbols Reference
 
-| Modifier | Mac Symbol | Windows/Linux Label |
-|----------|-----------|-------------------|
-| Meta (Cmd) | `⌘` | `Win` / `Super` |
-| Control | `⌃` | `Ctrl` |
-| Alt/Option | `⌥` | `Alt` |
-| Shift | `⇧` | `Shift` |
+On macOS, modifiers are displayed as symbols, and ordered per [Apple's Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/keyboards):
+
+| Modifier | Mac Symbol |
+|----------|-----------|
+| Control | `⌃` |
+| Option | `⌥` |
+| Shift | `⇧` |
+| Meta (Cmd) | `⌘` |
+
+On Windows and Linux, modifiers are displayed as text labels:
+
+| Modifier | Windows Label | Linux Label |
+|----------|---------------|-------------|
+| Meta | `Win` | `Super` |
+| Control | `Ctrl` | `Ctrl` |
+| Alt/Option | `Alt` | `Alt` |
+| Shift | `Shift` | `Shift` |
 
 ## Parsing and Normalization
 

diff --git a/docs/reference/functions/formatForDisplay.md b/docs/reference/functions/formatForDisplay.md
@@ -9,11 +9,12 @@ title: formatForDisplay
 function formatForDisplay(hotkey, options): string;
 ```
 
-Defined in: [format.ts:92](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/format.ts#L92)
+Defined in: [format.ts:93](https://github.com/TanStack/hotkeys/blob/main/packages/hotkeys/src/format.ts#L93)
 
 Formats a hotkey for display in a user interface.
 
-On macOS, uses symbols (⌘⇧S) in the same modifier order as [normalizeHotkeyFromParsed](normalizeHotkeyFromParsed.md).
+On macOS, uses symbols (⇧⌘S) in modifier order per [Apple's Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/keyboards):
+Control → Option → Shift → Command.
 On Windows/Linux, uses text (Ctrl+Shift+S) with `+` separators.
 The separator can be customized with `separatorToken`.
 
@@ -41,7 +42,7 @@ A formatted string suitable for display
 
 ```ts
 formatForDisplay('Mod+Shift+S', { platform: 'mac' })
-// Returns: '⌘ ⇧ S' (symbols separated by spaces on macOS)
+// Returns: '⇧ ⌘ S' (symbols separated by spaces on macOS)
 
 formatForDisplay('Mod+Shift+S', { platform: 'windows' })
 // Returns: 'Ctrl+Shift+S'

diff --git a/packages/hotkeys/src/format.ts b/packages/hotkeys/src/format.ts
@@ -8,6 +8,7 @@ import {
   PUNCTUATION_KEY_DISPLAY_LABELS,
   WINDOWS_MODIFIER_LABELS,
   detectPlatform,
+  resolveModifier,
 } from './constants'
 import {
   isModifierKey,
@@ -101,7 +102,11 @@ export function formatForDisplay(
     hotkey as RegisterableHotkey,
     platform,
   )
-  return normalizedHotkey
+
+  const formattedHotkey =
+    platform === 'mac' ? orderMacModifiers(normalizedHotkey) : normalizedHotkey
+
+  return formattedHotkey
     .split('+')
     .map((segment) => {
       if (isModifierKey(segment)) {
@@ -131,6 +136,27 @@ export function formatForDisplay(
     .join(separatorToken)
 }
 
+function orderMacModifiers(hotkey: string) {
+  const modifiers: Array<string> = []
+  const keys: Array<string> = []
+  hotkey.split('+').forEach((segment) => {
+    if (isModifierKey(segment)) {
+      const modifier =
+        segment === 'Mod' ? resolveModifier(segment, 'mac') : segment
+      modifiers.push(modifier)
+    } else {
+      keys.push(segment)
+    }
+  })
+
+  modifiers.sort(
+    (a, b) =>
+      MODIFIER_ORDER.indexOf(a as CanonicalModifier) -
+      MODIFIER_ORDER.indexOf(b as CanonicalModifier),
+  )
+  return modifiers.concat(keys).join('+')
+}
+
 /**
  * @deprecated Use {@link formatForDisplay} instead with `useSymbols: false` option.
  */