# Shortcuts

Register keyboard shortcuts and show the right keys for the user's platform.

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

```vue title="basic.vue"
<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>
```

Press N to create a note. Press Command+S on Mac or Control+S elsewhere to save. The buttons run the same actions.

## Register a Shortcut

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

```vue
<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:

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

```vue title="scope.vue"
<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>
```

Focus the note and type some text. Press Command+Enter on Mac or Control+Enter elsewhere to save, or Escape to clear it. Move focus outside the note to turn off its shortcuts.

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