# @kj455/react-use-search

> React hook for filtering and sorting

Latest version **1.0.2** (published 2022-03-15) · MIT license · 0 weekly downloads

## Install

```sh
npm install @kj455/react-use-search
pnpm add @kj455/react-use-search
yarn add @kj455/react-use-search
bun add @kj455/react-use-search
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.2 |
| Published | 2022-03-15 |
| First published | 2022-03-13 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 9.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 5 |
| Author | kj455 |
| Maintainers | kj455 |
| Keywords | react, search, filter, sort, hook, typescript |

## Links

- npm: https://www.npmjs.com/package/@kj455/react-use-search
- Repository: https://github.com/kj455/react-use-search
- Homepage: https://github.com/kj455/react-use-search#readme
- Issues: https://github.com/kj455/react-use-search/issues
- npm.io page: https://npm.io/package/@kj455/react-use-search

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads

## Recent versions

- 1.0.2 (latest) — 2022-03-15
- 1.0.1 — 2022-03-15
- 1.0.0 — 2022-03-15
- 0.1.0 — 2022-03-15
- 0.0.2 — 2022-03-15
- 0.0.1 — 2022-03-13

## README

# 🪝 react-use-search

This hook allows you to implement complex filtering and sorting operations on arrays with ease.

## 🌟 features

- **type-safe** filter and sort operations
- **multiple** filter conditions supporting both `AND` and `OR`
- **multiple** sorting conditions

## 🚀 Install

```bash
npm i @kj455/react-use-search
```

```bash
yarn add @kj455/react-use-search
```

## 📚 Usage

### 📝 Summary

1. Pass the following arguments to this hook. ('?' means optional)

   - `list` : the array to filter or sort
   - `opsions` : an object containing the following properties. details below.
     - `filterOptions`?
     - `sortOptions`?
   - `initKeys`? : an object containing the keys for the initial filter/sort conditions.

2. Get returned values. `results` is an array of filtered and sorted items.
3. Call `addFilter(KEY_NAME)` or `addSort(KEY_NAME)` to add a new filter/sort condition.
4. other methods are available for advanced usage. details below.

```ts
const { results, addFilter } = useSearch(list, { filterOptions: {...}, ... });
```

### 📖 Details

#### ↪️ `filterOptions`

`filterOptions` is an object which key is the name of the filter condition and value is an object containing the following properties.

- `condition` : a function which takes an item in list and returns a boolean, which is used for `Array.filter()` method.
- `groupKey`? : if specified, conditions with the same `groupKey` will be combined with **`OR`** condition.

NOTE: By default, **`AND`** condition is used for filtering.

#### :twisted_rightwards_arrows: `sortOptions`

`sortOptions` is an object which key is the name of the sort condition and value is an object containing the following properties.

- `rule` : a function which takes an item in list and returns a number, which is used for `Array.sort()` method.

if multiple sort keys are specified, the items will be sorted by the first sort condition, then by the second sort condition, and so on.

#### 🐶 Basic example

Basic filtering. Demo [here](https://codesandbox.io/s/dreamy-mcclintock-w36fqq?file=/src/App.tsx).

```ts
export default function App() {
  const list = [...];
  const { results, addFilter, removeFilter } = useSearch(list, {
    filterOptions: {
      VISIBLE: {
        condition: (item) => item.isVisible,
      },
      WITH_IMAGE: {
        condition: (item) => !!item.imageUrl,
      },
    },
    sortOptions: {
      ID_DESC: {
        rule: (a, b) => a.id - b.id
      },
      ID_ASC: {
        rule: (a, b) => b.id - a.id
      }
    }
  });

  return (...);
}
```

#### 🐱 Advanced example

- Combination of `AND` and `OR` conditions
- Specification of initial filter key

Demo [here](https://codesandbox.io/s/solitary-surf-ehoudx?file=/src/App.tsx).

```ts
const list = [
  { id: 1, name: "piccachu", category: "POKEMON", isHuman: false },
  { id: 2, name: "mew", category: "POKEMON", isHuman: false },
  { id: 3, name: "mario", category: "SUPER_MARIO", isHuman: true },
  { id: 4, name: "pinokio", category: "SUPER_MARIO", isHuman: false }
];

export default function App() {
  const { results, filterKeyList, addFilter, removeFilter } = useSearch(list, {
    filterOptions: {
      HUMAN: {
        condition: (item) => item.isHuman
      },
      POKEMON: {
        condition: (item) => item.category === "POKEMON",
        groupKey: "anime"
      },
      SUPER_MARIO: {
        condition: (item) => item.category === "SUPER_MARIO",
        groupKey: "anime"
      }
    },
  }, { filter: 'POKEMON' });

  return (...)
}
```

#### :memo: All Returned Values

| name          | description                                               |
| ------------- | --------------------------------------------------------- |
| results       | Array after filtered and sorted                           |
| filterKeyList | Array of keys for the current filter conditions           |
| filterOptions | Object same as filterOption received as argument          |
| setFilter     | Function to set filter KEY after emptying `filterKeyList` |
| addFilter     | Function to add filter KEY to `filterKeyList`             |
| removeFilter  | Function to remove filter KEY from `filterKeyList`        |
| resetFilter   | Function to empty `filterKeyList`                         |
| sortKeyList   | Array of keys for the current sort rules                  |
| sortOptions   | Object same as sortOption received as argument            |
| setSort       | Function to set sort KEY after emptying `sortKeyList`     |
| addSort       | Function to add sort KEY to `sortKeyList`                 |
| removeSort    | Function to remove sort KEY from `sortKeyList`            |
| resetSort     | Function to empty `sortKeyList`                           |

---
_Source: https://npm.io/package/@kj455/react-use-search · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._