# FormatForDisplayController

<!-- DO NOT EDIT: this page is autogenerated from the type comments -->

Defined in: [controllers/format-for-display.ts:57](https://github.com/TanStack/hotkeys/blob/main/packages/lit-hotkeys/src/controllers/format-for-display.ts#L57)

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

```ts
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

```ts
new FormatForDisplayController(_host, _options?): FormatForDisplayController;
```

Defined in: [controllers/format-for-display.ts:84](https://github.com/TanStack/hotkeys/blob/main/packages/lit-hotkeys/src/controllers/format-for-display.ts#L84)

#### Parameters

##### \_host

`ReactiveControllerHost`

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

##### \_options?

  \| [`FormatForDisplayControllerOptions`](../interfaces/FormatForDisplayControllerOptions.md)
  \| (() => [`FormatForDisplayControllerOptions`](../interfaces/FormatForDisplayControllerOptions.md)) = `{}`

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

#### Returns

`FormatForDisplayController`

## Properties

### format

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

Defined in: [controllers/format-for-display.ts:66](https://github.com/TanStack/hotkeys/blob/main/packages/lit-hotkeys/src/controllers/format-for-display.ts#L66)

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

```ts
(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

```ts
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

```ts
(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

```ts
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

```ts
(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

```ts
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

```ts
(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

```ts
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()

```ts
dispose(): void;
```

Defined in: [controllers/format-for-display.ts:108](https://github.com/TanStack/hotkeys/blob/main/packages/lit-hotkeys/src/controllers/format-for-display.ts#L108)

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.

#### Returns

`void`

***

### hostConnected()

```ts
hostConnected(): void;
```

Defined in: [controllers/format-for-display.ts:94](https://github.com/TanStack/hotkeys/blob/main/packages/lit-hotkeys/src/controllers/format-for-display.ts#L94)

Starts reading the layout, unless `keyboardLayout` is false.

#### Returns

`void`

#### Implementation of

```ts
ReactiveController.hostConnected
```

***

### hostUpdate()

```ts
hostUpdate(): void;
```

Defined in: [controllers/format-for-display.ts:99](https://github.com/TanStack/hotkeys/blob/main/packages/lit-hotkeys/src/controllers/format-for-display.ts#L99)

Follows a `keyboardLayout` option that a host property changed.

#### Returns

`void`

#### Implementation of

```ts
ReactiveController.hostUpdate
```