useKeyStroke

Category

Sensors

Export Size

1.01 kB

Last Changed

5 days ago

Listen for keyboard keystrokes. By default, listens on keydown events on window.

Demo

Usage

import { useKeyStroke } from '@reause/core'

useKeyStroke('ArrowDown', (e) => {
  e.preventDefault()
})

See this table for all key codes.

Return Value

Returns a stop function to remove the event listener.

const stop = useKeyStroke('Escape', handler)

// Later, stop listening
stop()

Listen To Multiple Keys

useKeyStroke(['s', 'S', 'ArrowDown'], (e) => {
  e.preventDefault()
})

// listen to all keys by passing `true` or skipping the key parameter
useKeyStroke(true, (e) => {
  e.preventDefault()
})
useKeyStroke((e) => {
  e.preventDefault()
})

Custom Key Predicate

You can pass a custom function to determine which keys should trigger the handler.

useKeyStroke(
  e => e.key === 'A' && e.shiftKey,
  (e) => {
    console.log('Shift+A pressed')
  },
)

Custom Event Target

useKeyStroke('A', (e) => {
  console.log('Key A pressed on document')
}, { target: document })

Ignore Repeated Events

The callback will trigger only once when pressing A and holding down. The dedupe option can also be a plain boolean — it is read on every received event.

useKeyStroke('A', (e) => {
  console.log('Key A pressed')
}, { dedupe: true })

Reference: KeyboardEvent.repeat

Passive Mode

Set passive: true to use a passive event listener.

useKeyStroke('A', handler, { passive: true })

Custom Keyboard Event

useKeyStroke('Shift', (e) => {
  console.log('Shift key up')
}, { eventName: 'keyup' })

Or

useKeyUp('Shift', () => console.log('Shift key up'))

Shorthands

• useKeyDown - alias for useKeyStroke(key, handler, {eventName: 'keydown'})
• useKeyPressed - alias for useKeyStroke(key, handler, {eventName: 'keypress'})
• useKeyUp - alias for useKeyStroke(key, handler, {eventName: 'keyup'})

Type Declarations

Toggle

export type KeyPredicate = (event: KeyboardEvent) => boolean

export type KeyFilter = true | string | string[] | KeyPredicate

export type KeyStrokeEventName = 'keydown' | 'keypress' | 'keyup'

export interface UseKeyStrokeOptions {
    eventName?: KeyStrokeEventName;
    target?: RefObject<EventTarget | null | undefined>;
    passive?: boolean;
    dedupe?: boolean;
}

export function useKeyStroke(key: KeyFilter, handler: (event: KeyboardEvent) => void, options?: UseKeyStrokeOptions): () => void

export function useKeyStroke(handler: (event: KeyboardEvent) => void, options?: UseKeyStrokeOptions): () => void

export function useKeyDown(key: KeyFilter, handler: (event: KeyboardEvent) => void, options?: Omit<UseKeyStrokeOptions, 'eventName'>): () => void

export function useKeyPressed(key: KeyFilter, handler: (event: KeyboardEvent) => void, options?: Omit<UseKeyStrokeOptions, 'eventName'>): () => void

export function useKeyUp(key: KeyFilter, handler: (event: KeyboardEvent) => void, options?: Omit<UseKeyStrokeOptions, 'eventName'>): () => void

Source

Source · Demo · VueUse

Contributors

Changelog

v0.1.0 on

4fede - fix(core): resolve useKeyStroke audit findings (#586)

77a38 - feat(core): add useKeyStroke (#33)