@gentleduck/shortcut

@gentleduck/shortcut

A lightweight React component for easily binding and handling keyboard shortcuts in your React applications.

Features

• Easy Integration: Integrate keyboard shortcuts into your React application effortlessly. Simply use the useDuckShortcut hook and pass the required props to handle key combinations or sequences.
• Support for Key Combinations: Handle key combinations like Ctrl+S or Command+K with ease. The component can take a single string or an array of key combinations.
• Support for Key Sequences: React to key sequences such as Up Up Down Down Left Right B A Enter. You can define these sequences as strings or arrays.
• Mixed Key Combinations and Sequences: Combine both key combinations and sequences to define more complex shortcuts.
• Global Keyboard Event Listener: The component adds a global keyboard event listener that works anywhere in the component tree without preventing events from bubbling or capturing.
• TypeScript Support: Fully implemented in TypeScript with type definitions, ensuring a smooth development experience with type safety.
• Case Insensitivity: The component handles key shortcuts in a case-insensitive manner, so you don’t need to worry about key case.
• No Conflict with Other Components: Use multiple instances of useDuckShortcut for different shortcuts without conflicts.

Installation

To install the toolkit, use npm or yarn:

npm install @gentleduck/shortcut
# or
yarn add @gentleduck/shortcut

Usage

Here's a quick guide on how to use the library:

import { useDuckShortcut } from '@gentleduck/shortcut'

const App = () => {
  useDuckShortcut({
    keys: ['ctrl+s'], // Key combinations or sequences
    onKeysPressed: () => {
      console.log('Ctrl+S was pressed!')
    },
  })

  return <div>Press Ctrl+S to trigger the shortcut</div>
}

Handling Multiple Shortcuts

You can handle multiple key combinations or sequences by passing them as an array:

import { useDuckShortcut } from '@gentleduck/shortcut'
const App = () => {
  useDuckShortcut({
    keys: ['ctrl+s', 'command+k'], // Multiple shortcuts
    onKeysPressed: () => {
      console.log('Ctrl+S or Command+K was pressed!')
    },
  })
  return <div>Press Ctrl+S or Command+K to trigger the shortcut</div>
}

API Reference

Here’s an API reference for @gentleduck/shortcut in MDX format, detailing the types and usage of the useDuckShortcut hook:

useDuckShortcut

The useDuckShortcut hook allows you to bind keyboard shortcuts to callback functions in your React components.

Importing

import { useDuckShortcut } from '@gentleduck/shortcut'

Usage

useDuckShortcut({
  keys: /* Key combinations or sequences */,
  onKeysPressed: /* Callback function */,
});

Parameters

keys

• Type: string | string[]
• Description: Defines the keyboard shortcuts to listen for. You can specify key combinations (e.g., 'ctrl+s', 'command+k') or key sequences (e.g., 'Up Up Down Down Left Right B A Enter').

Example

keys: 'ctrl+s'

or

keys: ['ctrl+s', 'command+k']

or

keys: 'Up Up Down Down Left Right B A Enter'

onKeysPressed

• Type: () => void
• Description: Callback function that gets called when the specified key combinations or sequences are pressed.

Example

onKeysPressed: () => {
  console.log('Shortcut triggered!')
}

Example

import { useDuckShortcut } from '@gentleduck/shortcut'

const App = () => {
  useDuckShortcut({
    keys: ['ctrl+s', 'command+k'], // Define your shortcuts
    onKeysPressed: () => {
      // Callback when shortcuts are pressed
      console.log('Shortcut triggered!')
    },
  })

  return <div>Press Ctrl+S or Command+K</div>
}

Notes

• Key Combinations: These are key presses that need to happen simultaneously (e.g., 'ctrl+s', 'command+shift+P').
• Key Sequences: These are key presses that need to happen in sequence (e.g., 'Up Up Down Down Left Right B A Enter').
• Case Sensitivity: Key names are case-insensitive.

Type Definitions

DuckShortcutProps

interface DuckShortcutProps {
  keys: string | string[] // Key combinations or sequences
  onKeysPressed: () => void // Callback when shortcuts are pressed
}

useDuckShortcut

declare function useDuckShortcut(props: DuckShortcutProps): void

Contributing

Contributions are welcome! Please open issues and pull requests on the GitHub repository.

License

MIT