Keybindings
provideKeybindings goes once near the app root. It creates the registry and owns the single keydown listener on the window. useHotkey goes in the component where the behavior lives, and the shortcut exists for as long as that component is mounted.
whenmakes a shortcut conditional. It is read at press time, so it can close over reactive state.- A press typed into a field is left to the field unless
modis held. - Option is never part of a shortcut, because macOS rewrites the character it reports. A press with Option held is ignored.
handShift+Hare separate shortcuts.shiftandmodare part of the press when set.modis Command on Apple devices and Control elsewhere.- Two shortcuts that claim the same press log a warning.
The provider has to sit above the consumer, so the two halves are separate files. Press J, Shift + J, or the platform’s command key with S. The save shortcut sets preventDefault, so the browser’s save dialog does not open.
Count: 0. Saved: 0 times.
Press J to add, Shift+J to reset, and Ctrl+S to save.
Code
<script lang="ts"> import { provideKeybindings } from "@viamrobotics/prime-ui";
import BasicHotkeys from "./BasicHotkeys.svelte";
provideKeybindings();</script>
<div class="not-content"> <BasicHotkeys /></div><script lang="ts"> import { Checkbox, Field, Input, Label } from "@viamrobotics/prime-ui"; import { formatKeybinding, useHotkey } from "@viamrobotics/prime-ui";
let count = $state(0); let saved = $state(0); let isEnabled = $state(true);
const increment = useHotkey({ id: "counter.increment", description: "Add one", group: "Counter", key: "j", when: () => isEnabled, run: () => count++, });
const reset = useHotkey({ id: "counter.reset", description: "Reset", group: "Counter", key: "j", shift: true, when: () => isEnabled, run: () => (count = 0), });
const save = useHotkey({ id: "counter.save", description: "Save", group: "Counter", key: "s", mod: true, preventDefault: true, run: () => saved++, });</script>
<div class="flex flex-col gap-2"> <p class="text-sm">Count: {count}. Saved: {saved} times.</p> <p class="text-sm"> Press <kbd>{formatKeybinding(increment)}</kbd> to add, <kbd>{formatKeybinding(reset)}</kbd> to reset, and <kbd>{formatKeybinding(save)}</kbd> to save. </p> <Field class="flex items-center gap-2"> <Checkbox bind:checked={isEnabled} /> <Label>Shortcuts enabled</Label> </Field> <Field class="flex flex-col gap-1"> <Label>Notes</Label> <Input placeholder="Typing here does not add" /> </Field></div>Listing shortcuts
Section titled “Listing shortcuts”useKeybindings().bindings holds every shortcut present right now, in registration order. Group them by group and print each with keybindingParts, which returns one string per key so each renders as its own <kbd>. useKeybinding lists a shortcut without running anything, for a key that something else handles.
Code
<script lang="ts"> import { provideKeybindings } from "@viamrobotics/prime-ui";
import ListingBody from "./ListingBody.svelte";
provideKeybindings();</script>
<div class="not-content"> <ListingBody /></div><script lang="ts"> import { keybindingParts, useHotkey, useKeybinding, useKeybindings, } from "@viamrobotics/prime-ui";
const keybindings = useKeybindings();
useHotkey({ id: "go.home", description: "Go home", group: "Navigation", key: "h", run: () => {} }); useHotkey({ id: "go.back", description: "Go back", group: "Navigation", key: "arrowleft", run: () => {} }); useHotkey({ id: "edit.undo", description: "Undo", group: "Editing", key: "z", mod: true, run: () => {} }); useHotkey({ id: "edit.redo", description: "Redo", group: "Editing", key: "z", mod: true, shift: true, run: () => {} }); useKeybinding({ id: "list.select", description: "Select an item", group: "Editing", key: "enter" });
const groups = $derived( Object.entries(Object.groupBy(keybindings.bindings, (binding) => binding.group)), );</script>
<div class="flex flex-col gap-4"> {#each groups as [group, bindings] (group)} <section> <h4 class="text-sm font-semibold">{group}</h4> <ul class="flex flex-col gap-1"> {#each bindings ?? [] as binding (binding.id)} <li class="flex items-center justify-between gap-4 text-sm"> <span>{binding.description}</span> <span class="flex gap-1"> {#each keybindingParts(binding) as part (part)} <kbd>{part}</kbd> {/each} </span> </li> {/each} </ul> </section> {/each}</div>Printing a shortcut
Section titled “Printing a shortcut”formatKeybinding prints a shortcut as one string, ⌘⇧Z on Apple devices and Ctrl+Shift+Z elsewhere. Use it where markup does not fit, such as a title or aria-keyshortcuts attribute. keybindingParts returns the same keys as an array, for a chip each. useHotkey returns the shortcut, so a button’s label and its key cannot drift.
| Function | Description |
|---|---|
provideKeybindings() |
Creates the registry, shares it with everything below, and owns the window listener. |
useKeybindings() |
Returns the registry from the nearest provider. Throws outside one. |
useHotkey(definition) |
Registers a shortcut and its run for as long as the component is mounted. Returns the shortcut. |
useKeybinding(binding) |
Lists a shortcut without a handler. Returns the shortcut. |
formatKeybinding(binding) |
The shortcut as one string. |
keybindingParts(binding) |
The shortcut as an array of printed keys. |
formatKey(key) |
One key as printed, so w reads W and arrowup reads ↑. |
The registry has bindings (every shortcut present), register(binding, handler?) (returns the remover), and matching(press).
Keybinding
Section titled “Keybinding”| Field | Type | Description |
|---|---|---|
id |
string |
Unique among the shortcuts present at once. |
description |
string |
What the shortcut does, for the listing. |
group |
string |
The heading a listing files the shortcut under. |
key |
string |
KeyboardEvent.key, lowercased. |
shift |
boolean |
Whether held Shift is part of the press. |
mod |
boolean |
Whether Command (Apple) or Control (elsewhere) is part of the press. |
preventDefault |
boolean |
Whether to cancel the browser’s own response to the press. |
useHotkey also takes run, which runs on the press, and when, which returns whether the shortcut applies right now.