mirror of
https://github.com/ArthurDanjou/ui.git
synced 2026-01-19 14:31:47 +01:00
146 lines
3.9 KiB
Markdown
146 lines
3.9 KiB
Markdown
---
|
|
description: 'Learn how to display and define keyboard shortcuts in your app.'
|
|
---
|
|
|
|
Some components like [Dropdown](/components/dropdown), [Command Palette](/components/command-palette) and [Tooltip](/components/tooltip) support the display of keyboard shortcuts.
|
|
|
|
```vue
|
|
<UDropdown :items="[[{ label: 'Edit', shortcuts: ['E'] }]]" />
|
|
```
|
|
|
|
Shortcuts are displayed and styled through the [Kbd](/components/kbd) component.
|
|
|
|
```vue
|
|
<template>
|
|
<div class="flex items-center gap-0.5">
|
|
<UKbd>⌘</UKbd>
|
|
<UKbd>K</UKbd>
|
|
</div>
|
|
</template>
|
|
```
|
|
|
|
::callout{icon="i-heroicons-light-bulb"}
|
|
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.
|
|
|
|
```vue
|
|
<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:
|
|
| Modifier | Description |
|
|
|----------|-------------|
|
|
| `meta` | Acts as `Command (⌘)` on macOS and `Control (Ctrl)` on Windows/Linux. |
|
|
| `ctrl` | Represents the `Control (Ctrl)` key across all operating systems. |
|
|
| `shift` | Represents the `Shift` key, only needed for alphabetic keys (e.g., `shift_e`). |
|
|
|
|
Examples of keys:
|
|
| Shortcut Key | Action |
|
|
|---------------|--------|
|
|
| `escape` | Triggers when `Esc` is pressed |
|
|
| `meta_k` | `⌘ + K` on Mac, `Ctrl + K` on Windows/Linux |
|
|
| `ctrl_k` | Triggers `Ctrl + K` on all OS |
|
|
| `shift_e` | Triggers `Shift + E` on all OS |
|
|
| `?` | Triggers `?` (Shift + `/` on US Mac keyboards) |
|
|
| `g-d` | Triggers when `g` then `d` are pressed within 800ms |
|
|
| `arrowleft` | Triggers when `←` is pressed (also: `arrowright`, `arrowup`, `arrowdown`) |
|
|
|
|
::callout{icon="i-heroicons-light-bulb"}
|
|
For a complete list of available shortcut keys, refer to the [`KeyboardEvent`](https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_key_values) API docs. Note the `KeyboardEvent.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.
|
|
|
|
```vue
|
|
<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`.
|
|
|
|
```ts
|
|
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`._
|
|
|
|
### Simple shortcut
|
|
|
|
In case the shortcut does not need any config, it can be written as a function.
|
|
|
|
```ts
|
|
defineShortcuts({
|
|
'?': () => openHelpModal()
|
|
})
|
|
```
|
|
|
|
## `useShortcuts`
|
|
|
|
To display shortcuts in your app according to the user's OS, you can use the `useShortcuts` composable.
|
|
|
|
```vue
|
|
<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_
|