react-cool-search

This is a React hook that provides a simples way to implement search/filter functionality on a list of objects based on their properties in React Components.

Installation

This package is distributed via npm.

$ yarn add react-cool-search
# or
$ npm install --save react-cool-search

Usage

Common use case.

import useSearch from 'react-cool-search';

interface User {
  id: number;
  name: string;
  lastName: string;
}

const users: User[] = [
  { id: 1, name: 'Lorem', lastName: 'Ipsum' },
  { id: 2, name: 'Foo', lastName: 'Bar' },
  { id: 3, name: 'Feijão', lastName: 'Arroz' },
  { id: 4, name: 'John', lastName: 'Doe' },
];

const Users = () => {
  const { data, query, handleChange } = useSearch(users);

  return (
    <div>
      <input
        type="text"
        placeholder="Search users"
        value={query}
        onChange={handleChange}
      />
      <ul>
        {data.map(user => (
          <li key={user.id + user.name}>{user.name}</li>
        ))}
      </ul>
    </div>
  );
};

Definig fields to search.

import useSearch from 'react-cool-search';

interface User {
  id: number;
  name: string;
  lastName: string;
}

const users: User[] = [
  { id: 1, name: 'Lorem', lastName: 'Ipsum' },
  { id: 2, name: 'Foo', lastName: 'Bar' },
  { id: 3, name: 'Feijão', lastName: 'Arroz' },
  { id: 4, name: 'John', lastName: 'Doe' },
];

const Users = () => {
  const { data, query, handleChange } = useSearch(users, { fields: ['name'] });

  return (
    <div>
      <input
        type="text"
        placeholder="Search users only by name"
        value={query}
        onChange={handleChange}
      />
      <ul>
        {data.map(user => (
          <li key={user.id + user.name}>{user.name}</li>
        ))}
      </ul>
    </div>
  );
};

API

useSearch<T>

const obj = useSearch<T>(collection: T[], options?: Options);

react-cool-search provides a hook as default export; it takes two parameters:
| Key | Type | Default | Description | | ------------ | ------ | ------- | ---------------------------------------------- | | collection | Array | | An array of elements of type T. | | options | object | | Configuration object. See Options. |

Options

The options object contains the following properies:
| Key | Type | Default | Description | | -------------- | -------------- | ---------------------------- | ---------------------------------------------------------------------------------------- | | initialQuery | string | "" | The query used for the initial collection returned from useSearch | | debounce | number | 300 | Number of milliseconds to delay before triggering the function to filter the collection. | | fields | Array | Object.keys(collection[0]) | Properties that must be searched for each object in the collection. |

Return object

The hook returns an object with the following properies:
| Key | Type | Default | Description | | -------------- | -------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | data | Array | initialQuery ? filterCollection(collection) : collection | A filtered version of collection passed to useSearch. | | status | string | initialQuery ? 'OK' : 'IDLE' | Search status. It might be IDLE or OK or NOT_FOUND | | query | string | initialQuery | The current query | | handleChange | function | (event) => {} | An event handler for an HTML input element. This is to be passes to the search input element as its onChange prop. | | setQuery | function | (query) => {} | A function to programmatically set the query value. |

License

MIT © Arimário Jesus

Contributors ✨

Thanks goes to these wonderful people (emoji key):

<td align="center"><a href="http://www.linkedin.com/in/arimariojesus"><img src="https://avatars.githubusercontent.com/u/64603070?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Ari Jesus</b></sub></a><br /><a href="https://github.com/arimariojesus/react-cool-search/commits?author=arimariojesus" title="Code">💻</a> <a href="https://github.com/arimariojesus/react-cool-search/commits?author=arimariojesus" title="Tests">⚠️</a> <a href="https://github.com/arimariojesus/react-cool-search/commits?author=arimariojesus" title="Documentation">📖</a> <a href="#maintenance-arimariojesus" title="Maintenance">🚧</a></td>

This project follows the all-contributors specification. Contributions of any kind welcome!