Skip to content

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.

  • when makes 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 mod is held.
  • Option is never part of a shortcut, because macOS rewrites the character it reports. A press with Option held is ignored.
  • h and Shift+H are separate shortcuts. shift and mod are part of the press when set.
  • mod is 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
Basic.svelte
<script lang="ts">
import { provideKeybindings } from "@viamrobotics/prime-ui";
import BasicHotkeys from "./BasicHotkeys.svelte";
provideKeybindings();
</script>
<div class="not-content">
<BasicHotkeys />
</div>
BasicHotkeys.svelte
<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>

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
Listing.svelte
<script lang="ts">
import { provideKeybindings } from "@viamrobotics/prime-ui";
import ListingBody from "./ListingBody.svelte";
provideKeybindings();
</script>
<div class="not-content">
<ListingBody />
</div>
ListingBody.svelte
<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>

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).

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.