Vue defineShortcuts Composable

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: MaybeRef<ShortcutsConfig>, options?: ShortcutsOptions): () => void

Define keyboard shortcuts for your application. Returns a function that removes the listener, in case you need to stop the shortcuts before the component unmounts.

Parameters

config

MaybeRef<ShortcutsConfig> required

An object where keys are shortcut definitions and values are either handler functions or shortcut configuration objects. Pass a ref to update the shortcuts reactively. A value of false, null or undefined skips that shortcut, which is how you enable one conditionally.

options

ShortcutsOptions

Optional configuration for the shortcuts behavior.

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 / command: Represents ⌘ Command on macOS and Ctrl on other platforms
ctrl: Represents Ctrl on all platforms
shift: Used for alphabetic keys when Shift is required
alt / option: Represents ⌥ Option on macOS and Alt on other platforms. Matched by physical key position, since Option rewrites the character on macOS

Special keys

Use these names to match special keys.

escape: Triggers on Esc key
enter: Triggers on Enter key
arrowleft, arrowright, arrowup, arrowdown: Trigger on respective arrow keys
tab: Triggers on Tab key
backspace: Triggers on Backspace key
delete: Triggers on Delete key
space: Triggers on the space bar. Requires layoutIndependent unless combined with alt

Shortcut configuration

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

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

Parameters

handler

() => void required

Function to be executed when the shortcut is triggered.

usingInput

boolean | string

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

Use usingInput to trigger a shortcut only when a specific input is focused.

<template>
  <B24Input 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>

Use the extractShortcuts utility to automatically define shortcuts from menu items.

Learn more about the extractShortcuts utility.

defineLocale

A utility to create a custom locale configuration for your application.

extendLocale

A utility to extend an existing locale with custom translation overrides.