Shortcuts

useShortcut registers a shortcut while your component is mounted. For a component that already accepts shortcut, such as a dialog trigger, use that prop directly.

<script setup lang="ts">
import { useShortcut, useShortcutHint } from "@ui-sdk/vue/shortcuts"
import { ref } from "vue"

const status = ref("Press N or the keys to save.")
const newNote = () => (status.value = "Note created")
const save = () => (status.value = "Saved")

useShortcut("n", newNote, { description: "New note" })
useShortcut("mod+s", save, { description: "Save" })
const { text: saveKeys, ariaKeyshortcuts: saveAria } = useShortcutHint("mod+s")
</script>

<template>
  <div data-slot="stack">
    <div data-slot="row">
      <button type="button" aria-keyshortcuts="N" @click="newNote">
        New note
        <kbd aria-hidden="true" data-slot="kbd">N</kbd>
      </button>
      <button type="button" :aria-keyshortcuts="saveAria" @click="save">
        Save
        <kbd aria-hidden="true" data-slot="kbd">{{ saveKeys }}</kbd>
      </button>
    </div>
    <output data-slot="output">{{ status }}</output>
  </div>
</template>

Register a Shortcut

Keys are joined with +. mod means Command on Apple platforms and Control elsewhere. This example also displays the keys using useShortcutHint:

<script setup lang="ts">
import { useShortcut, useShortcutHint } from "@ui-sdk/vue/shortcuts"
import { ref } from "vue"

const count = ref(0)
const addNote = () => count.value++
useShortcut("mod+enter", addNote, { description: "New note" })
const { text, ariaKeyshortcuts } = useShortcutHint("mod+enter")
</script>

<template>
  <button @click="addNote" :aria-keyshortcuts="ariaKeyshortcuts">
    New note ({{ count }}) <kbd aria-hidden="true">{{ text }}</kbd>
  </button>
</template>

Call the helper in setup. It unregisters when the component goes away. Keys and options can be getters; return null for keys to leave the shortcut unregistered.

Show the Keys

useShortcutHint supplies display text and aria-keyshortcuts. It keeps the server and first client render consistent, then updates for the user's platform after mount.

Its fields are computed refs. The example destructures them so the template unwraps them automatically.

Outside rendering, use formatShortcut for display text or ariaKeyshortcuts for the ARIA value, from the same entry.

While Someone Is Typing

Shortcuts with Command, Control, or Option can run in text fields. Plain letters and other keys stay available for typing. Set allowInInput: true when a shortcut should work there too, such as Escape to clear a search.

Limit a Shortcut to an Area

Use a named scope for an editor or another area. Turn it on while that area has focus:

<script setup lang="ts">
import { shortcuts, useShortcut } from "@ui-sdk/vue/shortcuts"
import { onScopeDispose, ref } from "vue"

const text = ref("")
useShortcut(
  "escape",
  () => {
    text.value = ""
  },
  { scope: "note", allowInInput: true }
)
onScopeDispose(() => shortcuts.setScope("note", false))
</script>

<template>
  <textarea
    aria-label="Note"
    v-model="text"
    @focus="shortcuts.setScope('note', true)"
    @blur="shortcuts.setScope('note', false)"
  />
</template>

Scope names are shared, so choose one for each area you want to enable together. A when function can add another condition, checked each time the keys are pressed.

<script setup lang="ts">
import { shortcuts, useShortcut } from "@ui-sdk/vue/shortcuts"
import { ref } from "vue"

const text = ref("")
const status = ref("Focus the note to turn on its shortcuts.")

useShortcut(
  "mod+enter",
  () => (status.value = `Characters saved: ${text.value.trim().length}`),
  {
    scope: "note",
    when: () => text.value.trim() !== "",
    description: "Save the note",
  }
)
useShortcut(
  "escape",
  () => {
    text.value = ""
    status.value = "Cleared"
  },
  { scope: "note", allowInInput: true, description: "Clear the note" }
)
</script>

<template>
  <div data-slot="stack">
    <textarea
      v-model="text"
      aria-label="Note"
      placeholder="Write a note…"
      @focus="shortcuts.setScope('note', true)"
      @blur="shortcuts.setScope('note', false)"
    />
    <output data-slot="output">{{ status }}</output>
  </div>
</template>

Inside a Popup

Page shortcuts pause while a modal is open. Pass layer, an element inside the popup or a getter that returns one, to make a shortcut belong to that popup. It runs only while that popup is open.

When shortcuts share the same keys, the topmost open layer wins, then the most recently registered shortcut.

List Available Shortcuts

Call shortcuts.list() when a help screen opens. It returns the shortcuts that can run now, including their keys, formatted hint, and description. Add descriptions when registering shortcuts so the help screen can explain each action.