---
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_