defineShortcuts

A composable to define keyboard shortcuts in your app.

Usage

Use the auto-imported defineShortcuts composable to define keyboard shortcuts.

<script setup lang="ts">
const open = ref(false)

defineShortcuts({
  meta_k: () => {
    open.value = !open.value
  }
})
</script>
  • Shortcuts are automatically adjusted for non-macOS platforms, converting meta to ctrl.
  • The composable uses VueUse's useEventListener to handle keydown events.
  • For a complete list of available shortcut keys, refer to the KeyboardEvent.key API documentation. Note that the key should be written in lowercase.

Learn how to display shortcuts in components in the Kbd component documentation.

API

defineShortcuts(config: ShortcutsConfig, options?: ShortcutsOptions): void

Define keyboard shortcuts for your application.

Parameters

An object where keys are shortcut definitions and values are either handler functions or shortcut configuration objects.

Optional configuration for the shortcuts behavior.

The delay between key presses to consider the shortcut as chained. Default is 250.

Shortcut definition

Shortcuts are defined using the following format:

  • Single key: 'a', 'b', '1', '?', etc.
  • Key combinations: Use _ to separate keys, e.g., 'meta_k', 'ctrl_shift_f'
  • Key sequences: Use - to define a sequence, e.g., 'g-d'

Modifiers

  • meta: Represents ⌘ Command on macOS and Ctrl on other platforms
  • ctrl: Represents Ctrl on all platforms
  • shift: Used for alphabetic keys when Shift is required

Special keys

  • escape: Triggers on Esc key
  • enter: Triggers on Enter key
  • arrowleft, arrowright, arrowup, arrowdown: Trigger on respective arrow keys

Shortcut configuration

Each shortcut can be defined as a function or an object with the following properties:

interface ShortcutConfig { handler: () => void; usingInput?: boolean | string }

Parameters

Function to be executed when the shortcut is triggered.

Controls when the shortcut should trigger based on input focus:

  • false (default): Shortcut only triggers when no input is focused
  • true: Shortcut triggers even when any input is focused
  • string: Shortcut only triggers when the specified input (by name) is focused

Examples

Basic usage

<script setup lang="ts">
defineShortcuts({
  '?': () => openHelpModal(),
  'meta_k': () => openCommandPalette(),
  'g-d': () => navigateToDashboard()
})
</script>

With input focus handling

The usingInput option allows you to specify that a shortcut should only trigger when a specific input is focused.

<template>
  <UInput v-model="query" name="queryInput" />
</template>

<script setup lang="ts">
const query = ref('')

defineShortcuts({
  enter: {
    usingInput: 'queryInput',
    handler: () => performSearch()
  },
  escape: {
    usingInput: true,
    handler: () => clearSearch()
  }
})
</script>

Extracting shortcuts from menu items

The extractShortcuts utility can be used to automatically define shortcuts from menu items:

<script setup lang="ts">
const items = [{
  label: 'Save',
  icon: 'i-lucide-file-down',
  kbds: ['meta', 'S'],
  onSelect() {
    save()
  }
}, {
  label: 'Copy',
  icon: 'i-lucide-copy',
  kbds: ['meta', 'C'],
  onSelect() {
    copy()
  }
}]

defineShortcuts(extractShortcuts(items))
</script>

useOverlay

A composable to programmatically control overlays.