1.0.2 • Published 2 years ago
@kj455/react-use-search v1.0.2
🪝 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
andOR
- multiple sorting conditions
🚀 Install
npm i @kj455/react-use-search
yarn add @kj455/react-use-search
📚 Usage
📝 Summary
Pass the following arguments to this hook. ('?' means optional)
list
: the array to filter or sortopsions
: an object containing the following properties. details below.filterOptions
?sortOptions
?
initKeys
? : an object containing the keys for the initial filter/sort conditions.
Get returned values.
results
is an array of filtered and sorted items.- Call
addFilter(KEY_NAME)
oraddSort(KEY_NAME)
to add a new filter/sort condition. - 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 forArray.filter()
method.groupKey
? : if specified, conditions with the samegroupKey
will be combined withOR
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 forArray.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
andOR
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 (...)
}
: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 |