stack/v1/packages/mosaic/framework/skills/vueuse-functions/references/useKeyModifier.md

category

category
Sensors

useKeyModifier

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!

Usage

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:

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:

import { useKeyModifier } from '@vueuse/core';
// ---cut---
const capsLockState1 = useKeyModifier('CapsLock'); // Ref<boolean | null>
const capsLockState2 = useKeyModifier('CapsLock', { initial: false }); // Ref<boolean>

Type Declarations

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> = ShallowRef<
  Initial extends boolean ? boolean : boolean | null
>;
export declare function useKeyModifier<Initial extends boolean | null>(
  modifier: KeyModifier,
  options?: UseModifierOptions<Initial>,
): UseKeyModifierReturn<Initial>;