FormatForDisplayController

Defined in: controllers/format-for-display.ts:57

A Lit ReactiveController whose format is formatForDisplay with the controller's platform option, or the detected platform without one. A platform passed to format 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 host updates when the layout loads or changes. See KeyboardLayoutController. A layoutMap passed to format wins. Labels have no layout on the server and for the host's first render, so a server-rendered element hydrates unchanged. Firefox and Safari report no layout, so labels there keep the key's US character.

Lit has no provider, so the options are the only defaults. Pass a getter to read them from host properties. Server-rendered elements should set platform from the request with detectPlatform(userAgent), so the server HTML matches the user's platform.

Example

class SaveButton extends LitElement {
  private formatForDisplay = new FormatForDisplayController(this)

  render() {
    return html`
      <button>Save <kbd>${this.formatForDisplay.format('Mod+S')}</kbd></button>
    `
  }
}

Implements

ReactiveController

Constructors

Constructor

new FormatForDisplayController(_host, _options?): FormatForDisplayController;

Defined in: controllers/format-for-display.ts:84

Parameters

_host

ReactiveControllerHost

The Lit component that owns this controller. The controller adds itself to it.

_options?

| FormatForDisplayControllerOptions | (() => FormatForDisplayControllerOptions) = {}

Options or a getter. platform is read for each label. keyboardLayout is read on connection and before host updates.

Returns

FormatForDisplayController

Properties

format

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

Defined in: controllers/format-for-display.ts:66

Formats a hotkey as a label, with the controller's platform and the user's keyboard layout filled in. It takes the same options as formatForDisplay and needs no this, so it can be passed around.

Call Signature

(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'

Call Signature

(hotkey, options): string[];

Formats a hotkey for display in a user interface.

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'

Call Signature

(hotkey, options?): string;

Formats a hotkey for display in a user interface.

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'

Call Signature

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

Formats a hotkey for display in a user interface.

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'

Methods

dispose()

dispose(): void;

Defined in: controllers/format-for-display.ts:108

Releases the controller now and removes it from its host, with the layout controller it added. Use it to remove a controller early: Lit's removeController alone leaves it active.