@solid-primitives/keyboard


A library of reactive promitives helping handling user's keyboard input.

- useKeyDownEvent — Provides a signal with the last keydown event.
- useKeyDownList — Provides a signal with the list of currently held keys
- useCurrentlyHeldKey — Provides a signal with the currently held single key.
- useKeyDownSequence — Provides a signal with a sequence of currently held keys, as they were pressed down and up.
- createKeyHold — Provides a signal indicating if provided key is currently being held down.
- createShortcut — Creates a keyboard shotcut observer.

Installation

``bash
npm install @solid-primitives/keyboard


or

pnpm add @solid-primitives/keyboard

or

yarn add @solid-primitives/keyboard
`

useKeyDownEvent

Provides a signal with the last keydown event.

This is a singleton root primitive that will reuse event listeners and signals across dependents.

$3

useKeyDownEvent takes no arguments, and returns a signal with the last keydown event.

`tsx
import { useKeyDownEvent } from "@solid-primitives/keyboard";

const event = useKeyDownEvent();

createEffect(() => {
const e = event();
console.log(e); // => KeyboardEvent | null

if (e) {
console.log(e.key); // => "Q" | "ALT" | ... or null
e.preventDefault(); // prevent default behavior or last keydown event
}
});
`

useKeyDownList

Provides a signal with the list of currently held keys, ordered from least recent to most recent.

This is a singleton root primitive that will reuse event listeners and signals across dependents.

$3

useKeyDownList takes no arguments, and returns a signal with the list of currently held keys

`tsx
import { useKeyDownList } from "@solid-primitives/keyboard";

const keys = useKeyDownList();

createEffect(() => {
console.log(keys()); // => string[] — list of currently held keys
});

{key => {key}};
`

useCurrentlyHeldKey

Provides a signal with the currently held single key. Pressing any other key at the same time will reset the signal to null.

This is a singleton root primitive that will reuse event listeners and signals across dependents.

$3

useCurrentlyHeldKey takes no arguments, and returns a signal with the currently held single key.

`tsx
import { useCurrentlyHeldKey } from "@solid-primitives/keyboard";

const key = useCurrentlyHeldKey();

createEffect(() => {
console.log(key()); // => string | null — currently held key
});
`

useKeyDownSequence

Provides a signal with a sequence of currently held keys, as they were pressed down and up.

This is a singleton root primitive that will reuse event listeners and signals across dependents.

$3

useKeyDownSequence takes no arguments, and returns a single signal.

`tsx
import { useKeyDownSequence } from "@solid-primitives/keyboard";

const sequence = useKeyDownSequence();

createEffect(() => {
console.log(sequence()); // => string[][] — sequence of currently held keys
});

// example sequence of pressing Ctrl + Shift + A
// [["Control"], ["Control", "Shift"], ["Control", "Shift", "A"]]
`

createKeyHold

Provides a boolean signal indicating if provided key is currently being held down.

Holding multiple keys at the same time will return false — holding only the specified one will return true.

$3

createKeyHold takes two arguments:

- key keyboard key to listen for
- options additional configuration:
- preventDefault — call e.preventDefault() on the keyboard event, when the specified key is pressed. _(Defaults to true)_

`tsx
import { createKeyHold } from "@solid-primitives/keyboard";

const pressing = createKeyHold("Alt", { preventDefault: false });

Is pressing Alt? {pressing() ? "YES" : "NO"}

;
`

createShortcut

Creates a keyboard shotcut observer. The provided callback will be called when the specified keys are pressed.

$3

createShortcut takes three arguments:

- keys — list of keys to listen for
- callback — callback to call when the specified keys are pressed
- options — additional configuration:
- preventDefault — call e.preventDefault() on the keyboard event, when the specified key is pressed. _(Defaults to true)_
- requireReset — If true, the shortcut will only be triggered once until all of the keys stop being pressed. Disabled by default.

`tsx
import { createShortcut } from "@solid-primitives/keyboard";

createShortcut(
["Control", "Shift", "A"],
() => {
console.log("Shortcut triggered");
},
{ preventDefault: false, requireReset: true },
);
`

$3

When preventDefault is true, e.preventDefault() will be called not only on the keydown event that have triggered the callback, but it will optimistically also prevend the default behavior of every previous keydown that will have the possibility to lead to the shotcut being pressed.

E.g. when listening for Control + Shift + A`, all three keydown events will be prevented.

DEMO

Working demo of some of the primitives in keyboard package:

https://codesandbox.io/s/solid-primitives-keyboard-demo-s2l84k?file=/index.tsx

Changelog

See CHANGELOG.md