React Hotkeys Selection

A React library for handling multi-item selection with full keyboard shortcuts and mouse gestures support, similar to native OS experiences. Use it on:

• ✅ Tables with checkboxes where you need to select rows, such as in GMail.
• ✅ Image galleries
• ✅ Lists of folders or files
• ✅ In any list of items that need selection!

Demo

Storybook Demo

Features

• ✅ Multi-selection: Support for selecting multiple items
• ⌨️ Keyboard shortcuts: Ctrl/Cmd+Click for individual selection, Shift+Click for ranges
• 🖱️ Selection strategy: Individual selection, toggle selection, or no selection
• 🎯 TypeScript: Fully typed with generic support
• 🔧 Flexible: Configurable selection behaviors and event handlers in your items
• 🚀 Optimized: Uses memoized callbacks for better performance

Installation

Install with pnpm or your preferred package manager:

pnpm add react-hotkeys-selection

Quick Start

1. Setup Provider

import { SelectionProvider } from 'react-hotkeys-selection'

const items = [
  { id: 1, name: 'Item 1' },
  { id: 2, name: 'Item 2' },
  { id: 3, name: 'Item 3' }
]

function App() {
  return (
    <SelectionProvider initialState={items}>
      <ItemList />
    </SelectionProvider>
  )
}

2. Use in Components

import { useSelection, useSelectionItem } from 'react-hotkeys-selection'

function ItemList() {
  const { selected, clear } = useSelection()

  return (
    <div>
      <button onClick={clear}>Clear ({selected.length})</button>
      {items.map((item) => (
        <Item
          key={item.id}
          item={item}
        />
      ))}
    </div>
  )
}

function Item({ item }) {
  const { isSelected, handleSelection } = useSelectionItem(item)

  return (
    <div
      onClick={handleSelection}
      style={{
        backgroundColor: isSelected ? '#e3f2fd' : 'white',
        padding: '8px',
        cursor: 'pointer'
      }}
    >
      {item.name}
    </div>
  )
}

API Reference

SelectionProvider

Provides selection context to child components.

Props: HotkeysSelectionProps<T>

• initialState: T[] - Array of selectable items
• strategy?: HotkeysSelectionStrategy - Individual selection 'single', toggle selection 'toggle', or no selection 'none' (default: 'single')
• useCtrlKey?: boolean - Enable Ctrl/Cmd+Event for individual selection (default: true)
• useShiftKey?: boolean - Enable Shift+Event for range selection (default: true)

useSelection<T>()

Main hook providing selection functionality.

Returns: HotkeysSelectionReturn<T>

Property	Type	Description
selected	T[]	Currently selected items
isSelected	(item: T) => boolean	Check if item is selected
handleSelection	(event: SyntheticEvent, item: T) => void	Event handler for items
clear	() => void	Clear all selection
add	(items: T[]) => void	Add items to selection
remove	(items: T[]) => void	Remove items from selection

useSelectionItem<T>(item: T)

Convenience hook for individual item components.

Returns: HotkeysSelectionItemReturn<T>

Property	Type	Description
isSelected	boolean	Whether this item is selected
handleSelection	(event: SyntheticEvent) => void	Pre-configured event handler

useSelectionCore<T>(props)

Low-level hook that can be used without the provider. Requires manual prop drilling to child components.

Props: HotkeysSelectionProps<T>

Returns: HotkeysSelectionReturn<T>

Note: When using useSelectionCore directly, you cannot use useSelectionItem as it requires the context provider. You'll need to pass the selection state manually to child components.

Selection Behaviors

Interaction	Behavior
Event	Selection by predefined strategy
Ctrl/Cmd + Event	Toggle clicked item without affecting others
Shift + Event	Select range from last individual item

Advanced Usage

Programmatic Selection

function Controls() {
  const { selected, add, remove, clear } = useSelection()

  const selectAll = () => add(items)
  const selectEvens = () => add(items.filter((_, i) => i % 2 === 0))

  return (
    <div>
      <button onClick={selectAll}>Select All</button>
      <button onClick={selectEvens}>Select Evens</button>
      <button onClick={clear}>Clear</button>
    </div>
  )
}

With TypeScript

interface User {
  id: number
  name: string
  email: string
}

function UserList() {
  const users: User[] = [
    /* ... */
  ]

  return (
    <SelectionProvider<User> initialState={users}>
      <UserTable />
    </SelectionProvider>
  )
}

function UserTable() {
  const { selected } = useSelection<User>()
  // selected is properly typed as User[]
}

Using useSelectionCore Directly

function DirectUsage() {
  const items = [
    /* ... */
  ]
  const selection = useSelectionCore({ initialState: items })

  return (
    <div>
      <button onClick={selection.clear}>Clear</button>
      {items.map((item) => (
        <Item
          key={item.id}
          item={item}
          selection={selection} // Manual prop drilling required
        />
      ))}
    </div>
  )
}

function Item({ item, selection }) {
  return (
    <div
      onClick={(e) => selection.handleSelection(e, item)}
      style={{
        backgroundColor: selection.isSelected(item) ? '#e3f2fd' : 'white'
      }}
    >
      {item.name}
    </div>
  )
}

Storybook Examples

This library includes comprehensive Storybook examples:

• Basic: Simple list selection
• Grid: Grid layout with selection
• WithControls: Advanced controls and programmatic selection

Performance

• Immutable state updates for React compatibility

Requirements

• React 16.8+
• TypeScript 4.5+

License

MIT © Benja Osuna