magic-keys

Default aliases resolved before matching combos.


Package	`@vizejs/composable/magic-keys`
Own the source	`vize lib pull composable:magic-keys`
Runtime exports	`DEFAULT_KEY_ALIASES`, `normalizeKeyName`, `useMagicKeys`, `useKeyPressed`
Gzip budget	2816 B

Usage

import { DEFAULT_KEY_ALIASES, normalizeKeyName, useMagicKeys, useKeyPressed } from "@vizejs/composable/magic-keys";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`normalizeKeyName`	input	experimental	safe	not-applicable	none	web, server, worker, native, desktop, terminal	—	—
`useMagicKeys`	input	experimental	deterministic-fallback	stable	caller, reactive-scope	web, desktop	`window`	`normalizeKeyName`, `tryOnScopeDispose`
`useKeyPressed`	input	experimental	deterministic-fallback	stable	caller, reactive-scope	web, desktop	`window`	`normalizeKeyName`, `tryOnScopeDispose`

API

`DEFAULT_KEY_ALIASES`

Default aliases resolved before matching combos.

const DEFAULT_KEY_ALIASES

`normalizeKeyName`

Normalize a key name the way combos are matched.

function normalizeKeyName( name: string, aliases: Readonly<Record<string, string>> = DEFAULT_KEY_ALIASES, ): string

`useMagicKeys`

Track pressed keys and expose reactive key combos. Both event.key and event.code are recorded (lowercased), so "a" and "keya" both match. Because some platforms (notably macOS with meta) swallow keyup for other keys while a modifier is held, releasing a modifier clears every non-modifier key; losing window focus clears everything. Nothing is pressed during server rendering, and listeners are removed with the owning reactive scope.

function useMagicKeys(options: UseMagicKeysOptions = {}): MagicKeys

`useKeyPressed`

Track whether any key matching a filter is held down. String filters are normalized like combos ("esc" matches Escape) and compared against both event.key and event.code. The state resets on window blur and during server rendering is always false.

function useKeyPressed( filter: KeyFilter, options: UseKeyboardTargetOptions = {}, ): Readonly<Ref<boolean>>

Types

`UseKeyboardTargetOptions`

Options shared by the keyboard composables.

Member	Type	Description
`target`?	`MaybeRefOrGetter<EventTarget \| null \| undefined>`	Event target that receives `keydown`/`keyup`.
`passive`?	`boolean`	Register passive listeners.

`UseMagicKeysOptions`

Options for useMagicKeys.

Member	Type	Description
`target`?	`MaybeRefOrGetter<EventTarget \| null \| undefined>`	Event target that receives `keydown`/`keyup`.
`passive`?	`boolean`	Register passive listeners.
`aliasMap`?	`Readonly<Record<string, string>>`	Extra aliases merged over `DEFAULT_KEY_ALIASES`. Keys and values are matched case-insensitively.
`onEventFired`?	`(event: KeyboardEvent) => void`	Called for every `keydown`/`keyup` after the pressed set has been updated. Useful for `preventDefault()` with `passive: false`.

`MagicKeys`

Reactive keyboard state returned by useMagicKeys.

Member	Type	Description
`current`	`ReadonlySet<string>`	Normalized names (`event.key` and `event.code`, lowercase) currently pressed.
`combos`	`Readonly<Record<string, ComputedRef<boolean>>>`	Proxy of combo refs created lazily on property access, e.g. `const { shift, ctrl_s } = keys.combos`.
`isPressed`	`<const Combo extends string>( combo: Combo & KeyCombo<Combo>, ) => ComputedRef<boolean>`	Create (or reuse) a ref that is `true` while every key of the combo is pressed.
`reset`	`() => void`	Forget every pressed key (for example after a modal steals focus).