Shortcuts

Credits

I just want to say that this composable is coming directly from Nuxt UI. I am not the creator of this composable, I just wanted to share it with you because I think it's a really cool feature to have in your project. You can find the original docs here: Nuxt UI - Shortcuts.

Thanks Nuxt UI ♥

defineShortcuts

The defineShortcuts composable allows you to define keyboard shortcuts in your app really easily. Try it out by pressing Ctrl + v

<template>
  <div />
</template>
<script lang="ts" setup>
  defineShortcuts({
    ctrl_v: {
      usingInput: false,
      handler: () => {
        useSonner("Nice!", { description: "You just used a shortcut!" });
      },
    },
  });
</script>

API

defineShortcuts(config: ShortcutsConfig, options?: ShortcutsOptions)

Define keyboard shortcuts for your application.

• config: An object where keys are shortcut definitions and values are either handler functions or shortcut configuration objects.
• options: Optional configuration for the shortcuts behavior.
  • chainDelay: The delay between key presses to consider the shortcut as chained. Default is 250.

Shortcuts keys are written as the literal keyboard key value. For a complete list of available shortcut keys, refer to the KeyboardEvent.key API documentation. Note that the key should be written in lowercase.

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

Examples of keys:

• escape: will trigger by hitting Esc
• meta_k: will trigger by hitting ⌘ and K at the same time on MacOS, and Ctrl and K on Windows and Linux
• ctrl_k: will trigger by hitting Ctrl and K at the same time on MacOS, Windows and Linux
• shift_e: will trigger by hitting Shift and E at the same time on MacOS, Windows and Linux
• ?: will trigger by hitting ? on some keyboard layouts, or for example Shift and /, which results in ? on US Mac keyboards
• g-d: will trigger by hitting g then d with a maximum delay of 800ms by default
• arrowleft: will trigger by hitting ← (also: arrowright, arrowup, arrowdown)

Shortcut Configuration

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

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

• handler: Function to be executed when the shortcut is triggered
• usingInput:
  • 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

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.

Simple shortcut

In case the shortcut does not need any config, it can be written as a function.

<script lang="ts" setup>
  defineShortcuts({
    "?": () => useSonner.info("Question Mark", { description: "This is the question mark key." }),
    "g-d": () => useSonner.info("G D", { description: "This is the G D key combination." }),
  });
</script>

useKbd

To get the OS specific meta key symbol, you can use the useKbd composable.

<script setup>
  const metaSymbol = computed(() => useKbd().getKbdKey("meta"));
</script>

<template>
  <UKbd>{{ metaSymbol }}</UKbd>
</template>

metaSymbol will display either ⌘ on MacOS or Ctrl on any other OS