react-selection-hooks
v0.2.3
Published
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.
Downloads
68
Readme
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