1---
2category: Sensors
3---
4 
5# useKeyModifier
6 
7Reactive [Modifier State](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/getModifierState). Tracks state of any of the [supported modifiers](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/getModifierState#browser_compatibility) - see Browser Compatibility notes.
8 
9<CourseLink href="https://vueschool.io/lessons/alt-drag-to-clone-tasks?friend=vueuse">Learn useKeyModifier with this FREE video lesson from Vue School!</CourseLink>
10 
11## Usage
12 
13```ts
14import { useKeyModifier } from '@vueuse/core'
15 
16const capsLockState = useKeyModifier('CapsLock')
17 
18console.log(capsLockState.value)
19```
20 
21## Events
22 
23You can customize which events will prompt the state to update. By default, these are `mouseup`, `mousedown`, `keyup`, `keydown`. To customize these events:
24 
25```ts
26import { useKeyModifier } from '@vueuse/core'
27 
28const capsLockState = useKeyModifier('CapsLock', { events: ['mouseup', 'mousedown'] })
29 
30console.log(capsLockState) // null
31 
32// Caps Lock turned on with key press
33console.log(capsLockState) // null
34 
35// Mouse button clicked
36console.log(capsLockState) // true
37```
38 
39## Initial State
40 
41By default, the returned ref will be `Ref<null>` until the first event is received. You can explicitly pass the initial state to it via:
42 
43```ts
44import { useKeyModifier } from '@vueuse/core'
45// ---cut---
46const capsLockState1 = useKeyModifier('CapsLock') // Ref<boolean | null>
47const capsLockState2 = useKeyModifier('CapsLock', { initial: false }) // Ref<boolean>
48```
49 
50## Type Declarations
51 
52```ts
53export type KeyModifier =
54  | "Alt"
55  | "AltGraph"
56  | "CapsLock"
57  | "Control"
58  | "Fn"
59  | "FnLock"
60  | "Meta"
61  | "NumLock"
62  | "ScrollLock"
63  | "Shift"
64  | "Symbol"
65  | "SymbolLock"
66export interface UseModifierOptions<Initial> extends ConfigurableDocument {
67  /**
68   * Event names that will prompt update to modifier states
69   *
70   * @default ['mousedown', 'mouseup', 'keydown', 'keyup']
71   */
72  events?: WindowEventName[]
73  /**
74   * Initial value of the returned ref
75   *
76   * @default null
77   */
78  initial?: Initial
79}
80export type UseKeyModifierReturn<Initial> = ShallowRef<
81  Initial extends boolean ? boolean : boolean | null
82>
83export declare function useKeyModifier<Initial extends boolean | null>(
84  modifier: KeyModifier,
85  options?: UseModifierOptions<Initial>,
86): UseKeyModifierReturn<Initial>
87```
88