Shortcuts
Keyboard shortcuts for your pages: useShortcut runs a function when some keys are pressed, <LnxKbd> shows those keys next to what they do, and <LnxShortcutsSheet> lists every shortcut available at that moment.
Showcase
Ctrl↵
<LnxKbd combo="mod+enter" />
combo
stringKeys joined with `+`, and a space for sequences: `'mod+enter'`, `'n'`, `'g i'`. `mod` is ⌘ on Mac and Ctrl elsewhere, `alt` is ⌥ or Alt and `shift` is ⇧ Default value: 'mod+enter'When to use
- For the actions people repeat many times in a page: new, save, search, go to another section.
- Always as a second way: every shortcut needs a button or a link that does the same, because touch screens have no keyboard, and
<LnxKbd>hides itself there.
Examples
A shortcut in a button
useShortcut listens while the component is mounted, also inside <KeepAlive>: a deactivated page stops listening. shortcutTitle writes the title of the button with its keys.
Saved 0 times
vue
<LnxButton :title="shortcutTitle('Save', 'mod+enter')" @click="saved++">
Save <LnxKbd combo="mod+enter" />
</LnxButton>
<span>Saved {{ saved }} times</span>1
2
3
4
2
3
4
ts
useShortcut('mod+enter', () => save(), { description: 'Save' });1
While typing
In a text field, single keys are text: only shortcuts with mod and escape apply. Write in the field and press ⌘↵ or Ctrl+↵.
vue
<LnxInput v-model="text" placeholder="Write and save with mod+enter" />1
Which one wins
- The newest registered wins, so the
nof a page takes over thenof its layout. enabledturns a shortcut off while it returnsfalse, as if it didn't exist: an Esc that only cancels an open editor, for example.- Sequences, like
'g i', allow one second between keys. ?and!already carry the shift in their key: write'?', not'shift+?'.
ts
useShortcut('n', () => createReceipt(), { description: 'New receipt' });
useShortcut('g i', () => router.push('/incidents'), { description: 'Go to incidents' });
useShortcut('escape', () => cancelEdit(), { enabled: () => isEditing.value });1
2
3
2
3
Shortcuts sheet
Render <LnxShortcutsSheet /> once, in App.vue. It opens and closes with ? and lists the shortcuts with a description that are active at that moment. Combos with the same description share a row.
App.vue
vue
<template>
<RouterView />
<LnxShortcutsSheet :rows="[{ description: 'Undo the last action', combos: ['mod+z'] }]" />
</template>1
2
3
4
2
3
4
| Prop | Type | Description |
|---|---|---|
combo | string | Shortcut that opens and closes the sheet. By default, '?' |
rows | ShortcutRow[] | Rows always listed after the shortcuts, for those not registered with useShortcut, like the undo of the toasts |
It also exposes toggle(), to open it from a button.
Helpers
isTyping(target): whether an event comes from a text field.shortcutKeys(combo): the labels of the keys, like['⌘', '↵'].shortcutTitle(label, combo): a title like'New receipt (N)'.useEventListener(target, type, handler, options):addEventListenerwhile the component is mounted and active, also inside<KeepAlive>.isMac: whethermodis ⌘.
API
Props
| Prop | Type | Description |
|---|---|---|
combo | string | Keys joined with +, and a space for sequences: 'mod+enter', 'n', 'g i'. mod is ⌘ on Mac and Ctrl elsewhere, alt is ⌥ or Alt and shift is ⇧Default: 'mod+enter' |
Accessibility
<LnxKbd>is hidden from screen readers: it's a visual hint, and the button next to it already says what it does.- Shortcuts don't take over the keys of a text field, except those with
modand Esc. - The sheet is a modal dialog named by its title. Esc closes it and the focus goes back where it was.
Types
ShortcutOptions
ts
export interface ShortcutOptions {
description?: string; /* Lists the shortcut in the shortcuts sheet */
enabled?: () => boolean; /* While it returns false, it's as if the shortcut didn't exist */
}1
2
3
4
2
3
4
ShortcutRow
ts
export interface ShortcutRow {
description: string; /* What the shortcut does */
combos: string[]; /* Combos that do it, like ['mod+z'] */
}1
2
3
4
2
3
4