ui/docs/content/1.getting-started/4.shortcuts.md

description

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

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

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

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

Simple shortcut

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