Key State Tracking Guide

TanStack Hotkeys provides three Vue composables for tracking live keyboard state: useHeldKeys, useHeldKeyCodes, and useKeyHold.

useHeldKeys

vue

<script setup lang="ts">
import { useHeldKeys } from '@tanstack/vue-hotkeys'

const heldKeys = useHeldKeys()
</script>

<template>
  <div>{{ heldKeys.length > 0 ? heldKeys.join(' + ') : 'No keys held' }}</div>
</template>

useHeldKeyCodes

vue

<script setup lang="ts">
import { useHeldKeyCodes } from '@tanstack/vue-hotkeys'

const heldCodes = useHeldKeyCodes()
</script>

useKeyHold

vue

<script setup lang="ts">
import { useKeyHold } from '@tanstack/vue-hotkeys'

const isShiftHeld = useKeyHold('Shift')
</script>

<template>
  <span :class="{ active: isShiftHeld }">Shift</span>
</template>

Common patterns

Hold-to-reveal UI

vue

<script setup lang="ts">
import { useKeyHold } from '@tanstack/vue-hotkeys'

const isShiftHeld = useKeyHold('Shift')
</script>

<template>
  <button v-if="isShiftHeld">Permanently Delete</button>
  <button v-else>Move to Trash</button>
</template>

Debugging key display

vue

<script setup lang="ts">
import {
  formatForDisplay,
  useHeldKeyCodes,
  useHeldKeys,
} from '@tanstack/vue-hotkeys'
import type { RegisterableHotkey } from '@tanstack/vue-hotkeys'

const heldKeys = useHeldKeys()
const heldCodes = useHeldKeyCodes()
</script>

<template>
  <div v-for="key in heldKeys" :key="key">
    <strong>{{
      formatForDisplay(key as RegisterableHotkey, { useSymbols: true })
    }}</strong>
    <span>{{ heldCodes[key] }}</span>
  </div>
</template>

Under the hood

All three composables subscribe to the singleton KeyStateTracker:

import { getKeyStateTracker } from '@tanstack/vue-hotkeys'

const tracker = getKeyStateTracker()
tracker.getHeldKeys()
tracker.isKeyHeld('Shift')

Modifier-held shortcut hints

useHotkeyHint answers whether held modifiers are relevant to a binding. Keep formatting and badge styling in your component:

const visible = useHotkeyHint(() => binding.value) // computed ref: visible.value

For Alt+Shift+[KeyK], holding Alt, Shift, or both reveals the hint. An extra Control hides it; releasing all modifiers or blurring the window hides it. Nonmodifier keys are ignored. AltGraph does not reveal hints. Pass { exact: true } to require all binding modifiers, or { platform: 'mac' } to resolve Mod explicitly. Supply the same platform used by the registration when overriding detection.

Combine the boolean with the action's enabled state. The helper does not register a shortcut or determine whether its target is focused. The core equivalent is matchesHeldModifiers(binding, heldKeys, options).