Skip to content

useKeyModifier ​

Category
Export Size
587 B
Last Changed
last week

Reactive Modifier State. Tracks state of any of the supported modifiers - see Browser Compatibility notes.

Learn useKeyModifier with this FREE video lesson from Vue School!

Demo ​

capsLock
numLock
scrollLock
shift
control
alt

Usage ​

ts
import { useKeyModifier } from '@vueuse/core'

const capsLockState = useKeyModifier('CapsLock')

console.log(capsLockState.value)

Events ​

You can customize which events will prompt the state to update. By default, these are mouseup, mousedown, keyup, keydown. To customize these events:

ts
import { useKeyModifier } from '@vueuse/core'

const capsLockState = useKeyModifier('CapsLock', { events: ['mouseup', 'mousedown'] })

console.log(capsLockState) // null

// Caps Lock turned on with key press
console.log(capsLockState) // null

// Mouse button clicked
console.log(capsLockState) // true

Initial State ​

By default, the returned ref will be Ref<null> until the first event is received. You can explicitly pass the initial state to it via:

ts
const capsLockState1 = useKeyModifier('CapsLock') // Ref<boolean | null>
const capsLockState2 = useKeyModifier('CapsLock', { initial: false }) // Ref<boolean>

Type Declarations ​

typescript
export type KeyModifier =
  | "Alt"
  | "AltGraph"
  | "CapsLock"
  | "Control"
  | "Fn"
  | "FnLock"
  | "Meta"
  | "NumLock"
  | "ScrollLock"
  | "Shift"
  | "Symbol"
  | "SymbolLock"
export interface UseModifierOptions<Initial> extends ConfigurableDocument {
  /**
   * Event names that will prompt update to modifier states
   *
   * @default ['mousedown', 'mouseup', 'keydown', 'keyup']
   */
  events?: WindowEventName[]
  /**
   * Initial value of the returned ref
   *
   * @default null
   */
  initial?: Initial
}
export type UseKeyModifierReturn<Initial> = Ref<
  Initial extends boolean ? boolean : boolean | null
>
export declare function useKeyModifier<Initial extends boolean | null>(
  modifier: KeyModifier,
  options?: UseModifierOptions<Initial>,
): UseKeyModifierReturn<Initial>

Source ​

Source • Demo • Docs

Contributors ​

Anthony Fu
Jelf
Anthony Fu
Joe Maylor

Changelog ​

v12.0.0-beta.1 on 11/21/2024
0a9ed - feat!: drop Vue 2 support, optimize bundles and clean up (#4349)

Released under the MIT License.