🪝 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

npm i @kj455/react-use-search

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.

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.

🔀 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.

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.

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 (...)
}

📝 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