react-selection-hooks
Our operating systems use click modifiers to make our lives easier when selecting things and so should our react apps! This project aims to build abstractions around managing a selection of items from an array.
Goals
- Easy to use, no configuration, and useful default click modifiers
- Customizable click handling (wip)
- API for handling most common selection state actions (clear, append, remove, etc)
- Mobile utilities (not started)
- High unit test coverage (not started)
- Ability to maintain selections while filtering (not started)
Installation
yarn
yarn add react-selection-hooks
npm
npm install --save react-selection-hooks
Peer dependencies:
"react": "^17.0.2", "react-dom": "^17.0.2"
Demo
https://ssteuteville.github.io/react-selection-hooks/
Features
- Easy to use Operating System Like Selection functionality
- Selection State management and utilities
- Pivot Mode (default, matches popular operating systems)
- Customizability API (create your own state reducer)
- Built-in typescript support
Usage
import React from 'react';
import useSelection from 'react-selection-hooks';
const items = Array.from({ length: 10 })
.map((_, i) => ({ key: `Key ${i}` }));
// for best performance this should be memoized or const
const getKey = item => item.key;
const MyComponent: React.FC = () => {
const {
// an array of selected items
selectedItems,
// the number of items selected
selectionCount,
// add one item to the selection
appendSelection,
// remove all items from selection
clearSelection,
// check if item is selected
isSelected,
// (item, mouseEvent) => void, mouse event handler with modifier support
onSelect,
// remove one item from selection
removeFromSelection,
// toggle whether an item is selected or not
toggleSelection,
// the ...other properites would be determined by the reducer
// passed into the optional reducer prop
state: { selectedItems, ...other },
// useSelection has optional `reducer` and `defaultState` parameters
} = useSelection(items, { getKey });
return (
<ul>
{
items.map(item => (
<li
key={item.key}
onClick={e => onSelect(item, e)}
style={{ border: isSelected(item) ? '1px solid blue' : undefined }}
>
{item.key}
</li>
)
}
</ul>
)
}
Coming Soon
- More click handling modes (currently defaults to windows/chromeos, macos will be next)
- A base reducer to use for building custom reducers
- Mobile features
- Better Documentation
- Better test coverage
Contributions
Currently just asking for ideas for a long-term api and opinions on usefulness/interest
Use this issue if you're interested: https://github.com/ssteuteville/react-selection-hooks/issues/1