react-selection-hooks
TypeScript icon, indicating that this package has built-in type declarations

0.2.3 • Public • Published

npmdownloads

npmversion

npmuserstars

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

/react-selection-hooks/

    Package Sidebar

    Install

    npm i react-selection-hooks

    Weekly Downloads

    48

    Version

    0.2.3

    License

    MIT

    Unpacked Size

    97.4 kB

    Total Files

    39

    Last publish

    Collaborators

    • ssteuteville