Learn how to display and define keyboard shortcuts in your app.
Some components like Dropdown, Command Palette and Tooltip support the display of keyboard shortcuts.
<UDropdown :items="[[{ label: 'Edit', shortcuts: ['E'] }]]" />
Shortcuts are displayed and styled through the Kbd component.
<template>
<div class="flex items-center gap-0.5">
<UKbd>⌘</UKbd>
<UKbd>K</UKbd>
</div>
</template>
You will have a preview of how shortcuts are rendered in each component page.
defineShortcuts
This module provides a defineShortcuts
composable that allows you to define keyboard shortcuts in your app really easily.
<template>
<UModal v-model="isOpen" />
</template>
<script setup lang="ts">
const isOpen = ref(false)
defineShortcuts({
meta_k: {
usingInput: true,
handler: () => { isOpen.value = !isOpen.value }
}
})
</script>
Shortcuts keys are written as the literal keyboard key value. Combinations are made with _
separator. Chained shortcuts are made with -
separator.
Modifiers are also available:
meta
: acts as Command
for MacOS and Control
for othersctrl
: acts as Control
shift
: acts as Shift
and is only necessary for alphabetic keysExamples of keys:
escape
: will trigger by hitting Esc
meta_k
: will trigger by hitting ⌘
and K
at the same time on MacOS, and Ctrl
and K
on Windows and Linuxctrl_k
: will trigger by hitting Ctrl
and K
at the same time on MacOS, Windows and Linuxshift_e
: will trigger by hitting Shift
and E
at the same time on MacOS, Windows and Linux?
: will trigger by hitting ?
on some keyboard layouts, or for example Shift
and /
, which results in ?
on US Mac keyboardsg-d
: will trigger by hitting g
then d
with a maximum delay of 800ms by defaultarrowleft
: will trigger by hitting ←
(also: arrowright
, arrowup
, arrowdown
)For a complete list of available shortcut keys, refer to the
KeyboardEvent
API docs. Note theKeyboardEvent.key
has to be written in lowercase.
usingInput
Prop: usingInput?: string | boolean
By default, usingInput
is false
, meaning it will only trigger when no input is focused. When set to true
, the shortcut will also trigger when any input is focused.
For a more advanced behavior, usingInput
can be set to the name of an input, so it only triggers when focusing this specific input.
<template>
<UInput v-model="query" name="queryInput" />
</template>
<script setup lang="ts">
const query = ref('')
defineShortcuts({
enter: {
usingInput: 'queryInput',
handler: () => {
// TODO
}
}
})
</script>
enter shortcut will only trigger when queryInput
is focused.
whenever
Prop: whenever?: WatchSource<boolean>[]
whenever
allows to add constraints on the shortcut triggering behavior. This array can contain Ref<boolean>
, ComputedRef<boolean>
or () => boolean
.
defineShortcuts({
meta_k: {
usingInput: true,
handler: () => { isOpen.value = !isOpen.value }
},
escape: {
usingInput: true,
whenever: [isOpen],
handler: () => { isOpen.value = false }
}
})
escape
shortcut will only trigger when isOpen
is true
.
In case the shortcut does not need any config, it can be written as a function.
defineShortcuts({
'?': () => openHelpModal()
})
useShortcuts
To display shortcuts in your app according to the user’s OS, you can use the useShortcuts
composable.
<script setup lang="ts">
const { metaSymbol } = useShortcuts()
</script>
<template>
<UKbd>{{ metaSymbol }}</UKbd>
</template>
metaSymbol
will display either ⌘
on MacOS or Ctrl
on any other OS