# AlpineHotkeys

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

Defined in: [types.ts:141](https://github.com/TanStack/hotkeys/blob/main/packages/alpine-hotkeys/src/types.ts#L141)

Registrations and reactive state owned by one Alpine component.

## Properties

### createAppHotkeyList

```ts
createAppHotkeyList: () => AlpineHotkeyState<AppHotkeyListItem<AppHotkey<string, HotkeyChord | HotkeySequence | null>>[]>;
```

Defined in: [types.ts:239](https://github.com/TanStack/hotkeys/blob/main/packages/alpine-hotkeys/src/types.ts#L239)

Read every app hotkey with its live status through `.value`.

#### Returns

[`AlpineHotkeyState`](AlpineHotkeyState.md)\<`AppHotkeyListItem`\<`AppHotkey`\<`string`, `HotkeyChord` \| `HotkeySequence` \| `null`\>\>[]\>

***

### createAppHotkeys

```ts
createAppHotkeys: () => AlpineHotkeyState<Readonly<Record<string, AppHotkey<string, HotkeyChord | HotkeySequence | null>>>>;
```

Defined in: [types.ts:237](https://github.com/TanStack/hotkeys/blob/main/packages/alpine-hotkeys/src/types.ts#L237)

Read the effective app hotkeys from `provideAppHotkeys` through `.value`.

#### Returns

[`AlpineHotkeyState`](AlpineHotkeyState.md)\<`Readonly`\<`Record`\<`string`, `AppHotkey`\<`string`, `HotkeyChord` \| `HotkeySequence` \| `null`\>\>\>\>

***

### createCustomHotkeys

```ts
createCustomHotkeys: () => AlpineCustomHotkeys;
```

Defined in: [types.ts:243](https://github.com/TanStack/hotkeys/blob/main/packages/alpine-hotkeys/src/types.ts#L243)

Read and change the user's custom hotkeys.

#### Returns

[`AlpineCustomHotkeys`](AlpineCustomHotkeys.md)

***

### createFormatForDisplay

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

Defined in: [types.ts:203](https://github.com/TanStack/hotkeys/blob/main/packages/alpine-hotkeys/src/types.ts#L203)

Returns `formatForDisplay` with the scope's `platform` as the default, 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. A getter or an `x-text` expression that calls the function runs
again when the layout arrives. See `createKeyboardLayout`. 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.

Create it once, then call the returned function anywhere.

#### Returns

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

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

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

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

#### Example

```ts
Alpine.data('saveButton', () => {
  const hotkeys = createHotkeysScope()
  const formatForDisplay = hotkeys.createFormatForDisplay()

  return {
    get label() {
      return formatForDisplay('Mod+S')
    },
    destroy() {
      hotkeys.destroy()
    },
  }
})
```

***

### createHeldKeyCodes

```ts
createHeldKeyCodes: () => AlpineHotkeyState<Record<string, string>>;
```

Defined in: [types.ts:156](https://github.com/TanStack/hotkeys/blob/main/packages/alpine-hotkeys/src/types.ts#L156)

Read the mapping of held logical names to physical codes through `.value`.

#### Returns

[`AlpineHotkeyState`](AlpineHotkeyState.md)\<`Record`\<`string`, `string`\>\>

***

### createHeldKeys

```ts
createHeldKeys: () => AlpineHotkeyState<string[]>;
```

Defined in: [types.ts:154](https://github.com/TanStack/hotkeys/blob/main/packages/alpine-hotkeys/src/types.ts#L154)

Read held logical key names through `.value`.

#### Returns

[`AlpineHotkeyState`](AlpineHotkeyState.md)\<`string`[]\>

***

### createHotkey

```ts
createHotkey: AlpineCreateHotkey;
```

Defined in: [types.ts:147](https://github.com/TanStack/hotkeys/blob/main/packages/alpine-hotkeys/src/types.ts#L147)

Register one hotkey: a chord such as `'Mod+S'`, a sequence such as
`['G', 'G']`, or an app hotkey. Getters track changing hotkeys and options.
`undefined`, `null`, or `''` registers nothing, for an optional shortcut.

***

### createHotkeyHint

```ts
createHotkeyHint: (hotkey, options?) => AlpineHotkeyState<boolean>;
```

Defined in: [types.ts:163](https://github.com/TanStack/hotkeys/blob/main/packages/alpine-hotkeys/src/types.ts#L163)

Read whether held modifiers reveal a hotkey through `.value`. No hotkey
(`undefined`, `null`, or `''`) is never visible.

#### Parameters

##### hotkey

[`MaybeGetter`](../type-aliases/MaybeGetter.md)\<
  \| `RegisterableHotkey`
  \| `AppHotkey`\<`string`, HotkeyChord \| HotkeySequence \| null\>
  \| `null`
  \| `undefined`\>

##### options?

[`MaybeGetter`](../type-aliases/MaybeGetter.md)\<`HeldModifierOptions`\>

#### Returns

[`AlpineHotkeyState`](AlpineHotkeyState.md)\<`boolean`\>

***

### createHotkeyRegistrations

```ts
createHotkeyRegistrations: () => HotkeyRegistrationsResult;
```

Defined in: [types.ts:168](https://github.com/TanStack/hotkeys/blob/main/packages/alpine-hotkeys/src/types.ts#L168)

Read live registrations, including disabled entries.

#### Returns

[`HotkeyRegistrationsResult`](HotkeyRegistrationsResult.md)

***

### createHotkeys

```ts
createHotkeys: (definitions, options?) => void;
```

Defined in: [types.ts:149](https://github.com/TanStack/hotkeys/blob/main/packages/alpine-hotkeys/src/types.ts#L149)

Reconcile a list of hotkeys. Definition options override common options.

#### Parameters

##### definitions

[`MaybeGetter`](../type-aliases/MaybeGetter.md)\<readonly [`AlpineHotkeyDefinition`](../type-aliases/AlpineHotkeyDefinition.md)[]\>

##### options?

[`MaybeGetter`](../type-aliases/MaybeGetter.md)\<[`AlpineHotkeyCommonOptions`](../type-aliases/AlpineHotkeyCommonOptions.md)\>

#### Returns

`void`

***

### createHotkeyScopesState

```ts
createHotkeyScopesState: () => AlpineHotkeyState<HotkeyScopesState>;
```

Defined in: [types.ts:170](https://github.com/TanStack/hotkeys/blob/main/packages/alpine-hotkeys/src/types.ts#L170)

Read the active, exclusive, allowed, and suspended scopes through `.value`.

#### Returns

[`AlpineHotkeyState`](AlpineHotkeyState.md)\<`HotkeyScopesState`\>

***

### createKeyboardLayout

```ts
createKeyboardLayout: () => AlpineHotkeyState<KeyboardLayoutMap | null>;
```

Defined in: [types.ts:235](https://github.com/TanStack/hotkeys/blob/main/packages/alpine-hotkeys/src/types.ts#L235)

Read the browser's keyboard layout through `.value`, or `null` until it
loads and in browsers that don't report one. The layout maps each physical
code to the character it types, such as `KeyQ` to `a` on a French AZERTY
keyboard. Only Chromium browsers report one.

Creating it is what loads the layout. The layout is read again when the
window regains focus, until the scope is destroyed.
`createFormatForDisplay` uses it, so you only need it for labels you draw
yourself.

To never ask the browser for the layout, set `keyboardLayout: false` in
the scope's default options. `.value` is then `null`.

#### Returns

[`AlpineHotkeyState`](AlpineHotkeyState.md)\<`KeyboardLayoutMap` \| `null`\>

#### Example

```ts
Alpine.data('moveKeys', () => {
  const hotkeys = createHotkeysScope()
  const layout = hotkeys.createKeyboardLayout()

  return {
    label(code: string) {
      return (layout.value?.get(code) ?? code).toUpperCase()
    },
    destroy() {
      hotkeys.destroy()
    },
  }
})
```

***

### createKeyHold

```ts
createKeyHold: (key) => AlpineHotkeyState<boolean>;
```

Defined in: [types.ts:158](https://github.com/TanStack/hotkeys/blob/main/packages/alpine-hotkeys/src/types.ts#L158)

Read whether a key is held through `.value`.

#### Parameters

##### key

[`MaybeGetter`](../type-aliases/MaybeGetter.md)\<`IndividualKey`\>

#### Returns

[`AlpineHotkeyState`](AlpineHotkeyState.md)\<`boolean`\>

***

### destroy

```ts
destroy: () => void;
```

Defined in: [types.ts:245](https://github.com/TanStack/hotkeys/blob/main/packages/alpine-hotkeys/src/types.ts#L245)

Release every registration, subscription, effect, and recorder. Idempotent.

#### Returns

`void`