useFormatForDisplay

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

Defined in: packages/ember-hotkeys/src/useFormatForDisplay.ts:43

Returns formatForDisplay with the scope's platform as the default, so labels match the user's platform. The returned function works anywhere, including templates, and reads the scope's defaults when called, so templates update when they change. An explicit platform option 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. The returned function reads the layout from the browser after the render in which it first formats a label. It has no owner, so it doesn't read the layout again when the window regains focus: see useKeyboardLayout for that. A layoutMap passed to the returned function wins. To never ask the browser for the layout, set keyboardLayout: false in the scope's default options. Firefox and Safari report no layout, so labels there keep the key's US character.

Server-rendered apps should set the scope's default platform from the request user agent, such as detectPlatform(fastboot.request.headers.get('user-agent')) with the FastBoot service.

Parameters#

scope?#

EmberHotkeysScope

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#

class SaveButton extends Component<{ Args: { hotkeys: EmberHotkeysScope } }> {
  formatForDisplay = useFormatForDisplay(this.args.hotkeys)

  <template><kbd>{{this.formatForDisplay "Mod+S"}}</kbd></template>
}