chore: consolidate new foundation and archive v1 (#1495)

2026-09-07 12:32:57 -05:00
parent 9a5fbdbda7 5d27700026
commit 127a54fdff
3511 changed files with 727899 additions and 10 deletions
@@ -0,0 +1,87 @@
+---
+category: Sensors
+---
+
+# useKeyModifier
+
+Reactive [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.
+
+<CourseLink href="https://vueschool.io/lessons/alt-drag-to-clone-tasks?friend=vueuse">Learn useKeyModifier with this FREE video lesson from Vue School!</CourseLink>
+
+## 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
+import { useKeyModifier } from '@vueuse/core';
+// ---cut---
+const capsLockState1 = useKeyModifier('CapsLock'); // Ref<boolean | null>
+const capsLockState2 = useKeyModifier('CapsLock', { initial: false }); // Ref<boolean>
+```
+
+## Type Declarations
+
+```ts
+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>;
+```