AlpineHotkeys

Defined in: types.ts:141

Registrations and reactive state owned by one Alpine component.

Properties#

createAppHotkeyList#

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

Defined in: types.ts:239

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

Returns#

AlpineHotkeyState<AppHotkeyListItem<AppHotkey<string, HotkeyChord | HotkeySequence | null>>[]>

createAppHotkeys#

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

Defined in: types.ts:237

Read the effective app hotkeys from provideAppHotkeys through .value.

Returns#

AlpineHotkeyState<Readonly<Record<string, AppHotkey<string, HotkeyChord | HotkeySequence | null>>>>

createCustomHotkeys#

createCustomHotkeys: () => AlpineCustomHotkeys;

Defined in: types.ts:243

Read and change the user's custom hotkeys.

Returns#

AlpineCustomHotkeys

createFormatForDisplay#

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

Defined in: types.ts:203

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#

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

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

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

createHeldKeyCodes#

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

Defined in: types.ts:156

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

Returns#

AlpineHotkeyState<Record<string, string>>

createHeldKeys#

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

Defined in: types.ts:154

Read held logical key names through .value.

Returns#

AlpineHotkeyState<string[]>

createHotkey#

createHotkey: AlpineCreateHotkey;

Defined in: types.ts:147

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#

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

Defined in: types.ts:163

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

Parameters#

hotkey#

MaybeGetter< | RegisterableHotkey | AppHotkey<string, HotkeyChord | HotkeySequence | null> | null | undefined>

options?#

MaybeGetter<HeldModifierOptions>

Returns#

AlpineHotkeyState<boolean>

createHotkeyRegistrations#

createHotkeyRegistrations: () => HotkeyRegistrationsResult;

Defined in: types.ts:168

Read live registrations, including disabled entries.

Returns#

HotkeyRegistrationsResult

createHotkeys#

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

Defined in: types.ts:149

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

Parameters#

definitions#

MaybeGetter<readonly AlpineHotkeyDefinition[]>

options?#

MaybeGetter<AlpineHotkeyCommonOptions>

Returns#

void

createHotkeyScopesState#

createHotkeyScopesState: () => AlpineHotkeyState<HotkeyScopesState>;

Defined in: types.ts:170

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

Returns#

AlpineHotkeyState<HotkeyScopesState>

createKeyboardLayout#

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

Defined in: types.ts:235

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<KeyboardLayoutMap | null>

Example#

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#

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

Defined in: types.ts:158

Read whether a key is held through .value.

Parameters#

key#

MaybeGetter<IndividualKey>

Returns#

AlpineHotkeyState<boolean>

destroy#

destroy: () => void;

Defined in: types.ts:245

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

Returns#

void