useFormatForDisplay

function useFormatForDisplay(): {
  (hotkey, options): string[][];
  (hotkey, options): string[];
  (hotkey, options?): string;
  (hotkey, options): string | string[] | string[][];
};

Defined in: useFormatForDisplay.ts:38

Returns formatForDisplay with the platform from HotkeysProvider, or the detected platform without one. A platform passed to the returned function wins.

Physical bindings such as [KeyQ] are labeled with the character the key types for this user in Chromium browsers, once the keyboard layout has loaded. See useKeyboardLayout. A layoutMap passed to the returned function wins. Firefox and Safari report no layout, so labels there keep the key's US character.

Call the hook once at the top of the component; the returned function can be called anywhere, such as in a loop or a condition. Server-rendered apps should set the provider's defaultOptions.platform from the request with detectPlatform(userAgent), so the server HTML matches the user's platform.

Returns#

(hotkey, options): string[][];

Formats a hotkey for display in a user interface.

In a server-rendered app, format labels with your adapter's formatter, such as useFormatForDisplay, or pass platform. Called directly, formatForDisplay never reads a provider's platform. Without a platform option, it renders Linux labels on the server, so Mac users get a different label after hydration.

On macOS, uses symbols (⇧⌘S) in Control, Option, Shift, Command order. Display ordering does not change the normalized hotkey used for registration. On Windows/Linux, uses text (Ctrl+Shift+S) with + separators. The separator can be customized with separatorToken. Physical codes use conventional display labels: [KeyS] becomes S and [Digit2] becomes 2. Keys with no US key use their keycap legends: [IntlBackslash] and [IntlRo] become \ and [IntlYen] becomes ¥. These labels do not infer the active keyboard layout or change matching. Supply a resolved layoutMap for layout-aware labels; keyLabels overrides both layout entries and fallback labels. Sequence steps are formatted individually and joined with sequenceSeparator (a space by default).

A key reported by a KeyboardEvent, such as a held key from KeyStateTracker, can be outside the key types: pass it as { key }.

Parameters#

hotkey#

readonly DisplayHotkeyChord[]

A logical or physical hotkey string, raw object, ParsedHotkeyChord, or sequence

options#

FormatDisplayOptions & object

Formatting options

Returns#

string[][]

Display text, or individual key labels when parts is true (one array per step for sequences)

Example#

formatForDisplay('Mod+Shift+S', { platform: 'mac' })
// Returns: '⇧ ⌘ S' (symbols separated by spaces on macOS)

formatForDisplay('Mod+Shift+S', { platform: 'windows' })
// Returns: 'Ctrl+Shift+S'

formatForDisplay('Escape')
// Returns: 'Esc' (on all platforms)

formatForDisplay('Shift', { platform: 'mac' })
// Returns: '⇧'

formatForDisplay({ key: heldKey })
// A key from a KeyboardEvent, such as a held key

formatForDisplay(['G', 'H'])
// Returns: 'G H'

(hotkey, options): string[];

Formats a hotkey for display in a user interface.

In a server-rendered app, format labels with your adapter's formatter, such as useFormatForDisplay, or pass platform. Called directly, formatForDisplay never reads a provider's platform. Without a platform option, it renders Linux labels on the server, so Mac users get a different label after hydration.

On macOS, uses symbols (⇧⌘S) in Control, Option, Shift, Command order. Display ordering does not change the normalized hotkey used for registration. On Windows/Linux, uses text (Ctrl+Shift+S) with + separators. The separator can be customized with separatorToken. Physical codes use conventional display labels: [KeyS] becomes S and [Digit2] becomes 2. Keys with no US key use their keycap legends: [IntlBackslash] and [IntlRo] become \ and [IntlYen] becomes ¥. These labels do not infer the active keyboard layout or change matching. Supply a resolved layoutMap for layout-aware labels; keyLabels overrides both layout entries and fallback labels. Sequence steps are formatted individually and joined with sequenceSeparator (a space by default).

A key reported by a KeyboardEvent, such as a held key from KeyStateTracker, can be outside the key types: pass it as { key }.

Parameters#

hotkey#

DisplayHotkeyChord

A logical or physical hotkey string, raw object, ParsedHotkeyChord, or sequence

options#

FormatDisplayOptions & object

Formatting options

Returns#

string[]

Display text, or individual key labels when parts is true (one array per step for sequences)

Example#

formatForDisplay('Mod+Shift+S', { platform: 'mac' })
// Returns: '⇧ ⌘ S' (symbols separated by spaces on macOS)

formatForDisplay('Mod+Shift+S', { platform: 'windows' })
// Returns: 'Ctrl+Shift+S'

formatForDisplay('Escape')
// Returns: 'Esc' (on all platforms)

formatForDisplay('Shift', { platform: 'mac' })
// Returns: '⇧'

formatForDisplay({ key: heldKey })
// A key from a KeyboardEvent, such as a held key

formatForDisplay(['G', 'H'])
// Returns: 'G H'

(hotkey, options?): string;

Formats a hotkey for display in a user interface.

In a server-rendered app, format labels with your adapter's formatter, such as useFormatForDisplay, or pass platform. Called directly, formatForDisplay never reads a provider's platform. Without a platform option, it renders Linux labels on the server, so Mac users get a different label after hydration.

On macOS, uses symbols (⇧⌘S) in Control, Option, Shift, Command order. Display ordering does not change the normalized hotkey used for registration. On Windows/Linux, uses text (Ctrl+Shift+S) with + separators. The separator can be customized with separatorToken. Physical codes use conventional display labels: [KeyS] becomes S and [Digit2] becomes 2. Keys with no US key use their keycap legends: [IntlBackslash] and [IntlRo] become \ and [IntlYen] becomes ¥. These labels do not infer the active keyboard layout or change matching. Supply a resolved layoutMap for layout-aware labels; keyLabels overrides both layout entries and fallback labels. Sequence steps are formatted individually and joined with sequenceSeparator (a space by default).

A key reported by a KeyboardEvent, such as a held key from KeyStateTracker, can be outside the key types: pass it as { key }.

Parameters#

hotkey#

DisplayHotkey

A logical or physical hotkey string, raw object, ParsedHotkeyChord, or sequence

options?#

FormatDisplayOptions & object

Formatting options

Returns#

string

Display text, or individual key labels when parts is true (one array per step for sequences)

Example#

formatForDisplay('Mod+Shift+S', { platform: 'mac' })
// Returns: '⇧ ⌘ S' (symbols separated by spaces on macOS)

formatForDisplay('Mod+Shift+S', { platform: 'windows' })
// Returns: 'Ctrl+Shift+S'

formatForDisplay('Escape')
// Returns: 'Esc' (on all platforms)

formatForDisplay('Shift', { platform: 'mac' })
// Returns: '⇧'

formatForDisplay({ key: heldKey })
// A key from a KeyboardEvent, such as a held key

formatForDisplay(['G', 'H'])
// Returns: 'G H'

(hotkey, options): string | string[] | string[][];

Formats a hotkey for display in a user interface.

In a server-rendered app, format labels with your adapter's formatter, such as useFormatForDisplay, or pass platform. Called directly, formatForDisplay never reads a provider's platform. Without a platform option, it renders Linux labels on the server, so Mac users get a different label after hydration.

On macOS, uses symbols (⇧⌘S) in Control, Option, Shift, Command order. Display ordering does not change the normalized hotkey used for registration. On Windows/Linux, uses text (Ctrl+Shift+S) with + separators. The separator can be customized with separatorToken. Physical codes use conventional display labels: [KeyS] becomes S and [Digit2] becomes 2. Keys with no US key use their keycap legends: [IntlBackslash] and [IntlRo] become \ and [IntlYen] becomes ¥. These labels do not infer the active keyboard layout or change matching. Supply a resolved layoutMap for layout-aware labels; keyLabels overrides both layout entries and fallback labels. Sequence steps are formatted individually and joined with sequenceSeparator (a space by default).

A key reported by a KeyboardEvent, such as a held key from KeyStateTracker, can be outside the key types: pass it as { key }.

Parameters#

hotkey#

DisplayHotkey

A logical or physical hotkey string, raw object, ParsedHotkeyChord, or sequence

options#

FormatDisplayOptions

Formatting options

Returns#

string | string[] | string[][]

Display text, or individual key labels when parts is true (one array per step for sequences)

Example#

formatForDisplay('Mod+Shift+S', { platform: 'mac' })
// Returns: '⇧ ⌘ S' (symbols separated by spaces on macOS)

formatForDisplay('Mod+Shift+S', { platform: 'windows' })
// Returns: 'Ctrl+Shift+S'

formatForDisplay('Escape')
// Returns: 'Esc' (on all platforms)

formatForDisplay('Shift', { platform: 'mac' })
// Returns: '⇧'

formatForDisplay({ key: heldKey })
// A key from a KeyboardEvent, such as a held key

formatForDisplay(['G', 'H'])
// Returns: 'G H'

Example#

function SaveButton() {
  const formatForDisplay = useFormatForDisplay()

  return (
    <button>
      Save <kbd>{formatForDisplay('Mod+S')}</kbd>
    </button>
  )
}