React Multi Search

A react hook to filter data based on multiple search queries.

!NPM License
!NPM Version
!npm bundle size
!NPM Type Definitions

Features

- 🗃️ Support for various data types
- 📈 Range queries for numbers and dates
- 📜 Search suggestions
- 📊 Support for categorized data
- ✨ Headless, bring your own UI
- 🌐 TypeScript support

Supported data types

- String
- Can be case-sensitive or case-insensitive (default).
- Exact matches can be done by enclosing the query in double quotes.
- Can come with search suggestions, which is the aggregated possible
values for a specific field.
- Boolean
- Support for various truthy and falsy queries (true, yes, 1, etc.)
or provide your own.
- Number
- Support for range queries with operators: >, >=, <, <=, and !=.
- Date
- Support for range queries with operators like numbers.
- Time and timezone are ignored.

_Other data types will be treated as strings._

Demo

To see the hook in action, you can check the Storybook demo.

Installation

npm:

``sh npm i react-multi-search`

yarn:

`sh yarn add react-multi-search`

`Usage`

`jsx import { useState } from 'react'; import { useMultiSearch } from 'react-multi-search';

const MyComponent = () => { const initialData = [ { name: 'John Doe', age: 20, gender: 'Male' }, { name: 'Jane Doe', age: 25, gender: 'Female' }, // ... ];

const [filteredData, setFilteredData] = useState([]);

const { states: { searchString, searchField, searchSuggestions, searchQueries, isMenuOpen, shownMenu, }, actions: { clearInput, addSearchQuery, deleteSearchQuery, deleteAllSearchQueries, onMenuKeyDown, onSearchFieldSelect, onAllSearchFieldSelect, onSearchSuggestionSelect, openMenu, }, inputProps, anchorRef, listRef, } = useMultiSearch({ initialData, setFilteredData, fields: [ { value: 'name', label: 'Name' }, { value: 'age', label: 'Age' }, { value: 'gender', label: 'Gender', showSearchSuggestions: true }, ], });

return ( <> {/ search bar ------------------------------------------------------- /}

{/ search queries --------------------------------------------------- /} style={{ listStyle: 'none', padding: 0, }} > {searchQueries.map((query, index) => (


            
              {query.field === '_default'
                ? query.value
                :

${query.fieldLabel}: ${query.value}


        ))}
      
      
      {/ dropdown menu ---------------------------------------------------- /}
      {isMenuOpen && (
        

          
            {shownMenu === 'fields' && (
              <>
                Search by:

                
                                      onClick={onAllSearchFieldSelect}
                    disabled={searchField.value === '_default'}
                  >
                    All
                  
                

                {...props.fields.map((field) => (
                  
                                          onClick={() => onSearchFieldSelect(field)}
                      disabled={searchField.value === field.value}
                    >
                      {field.label}
                    
                  

                ))}
              
            )}
            {shownMenu === 'searchSuggestions' && (
              <>
                Search suggestions:

                {searchSuggestions?.map(
                  (value) => (
                    
                      
                    

                  )
                ) ?? No suggestions
}
              
            )}
          

        

      )}

{/ ... /} ); };`

See the demo code for a more comprehensive example.

`API`

`$3`

- initialData(required) -T[]- The initial data to filter. This should be an array of objects without categorization. If you want to categorize your data, use the separatecategorizer function.

- setFilteredData(required) -Dispatch> | Dispatch>>- setState function to update the filtered data. - Since this is a headless hook, the filtered data should be managed by the consuming component for reusability.

- fields(required) -(FieldWithSuggestions | FieldWithoutSuggestions)[]- The fields to search in. Each item in the array can be of typeFieldWithSuggestions where all keys should have the value of type string or boolean, or FieldWithoutSuggestions for other data types.

- categorizer-(data: T[]) => Record)[]>- Function to categorize and group the filtered data. - This is separated frominitialData to optimize performance when filtering.

- showEmptyCategories-boolean- Defaults tofalse. - Show categories that have no items. - This is only used whencategorizer is provided.

- shouldInitialize-boolean- Defaults totrue. - Control whether the hook should initialize or not. - This is useful when you want to delay the initialization of the hook until the data is ready.

- globalSearchReplacement-keyof T- The field to use for global search when no specific field is selected. - This is used when the search field is set to'_default'.

- overrideExistingQueriesWithSameField-boolean- Override existing queries with the same field.

- caseSensitive-boolean- Defaults tofalse. - Whether the comparison should be case-sensitive or not.

- trueLabel-string- Defaults toYes. - The label fortrue value on search suggestions.

- falseLabel-string- Defaults toNo. - The label forfalse value on search suggestions.

- truthyValues-string[]- Defaults to['true', '1', 'on', 'yes', 'y', 't', '✓']- A list of truthy values to match against boolean values.

- falsyValues-string[]- Defaults to['false', '0', 'off', 'no', 'n', 'f', 'x']- A list of falsy values to match against boolean values.

`$3`

- fields[number].value(required) -{ [K in keyof T]: T[K] extends string | boolean ? K : never; }[keyof T] for FieldWithSuggestions-{ [K in keyof T]: T[K] extends string | boolean ? never : K; }[keyof T] for FieldWithoutSuggestions- The field to search.

- fields[number].label(required) -string- The label for the field.

- fields[number].showSearchSuggestions-boolean (default: false) - Show search suggestions for this field. - This only applies toFieldWithoutSuggestions

- fields[number].strictSuggestions-boolean (default: false) - Enclose suggestions in double quotes to treat as exact match. - This only applies toFieldWithoutSuggestions

- fields[number].searchSuggestions-T[FieldWithSuggestions['value']][]- The search suggestions for this field. - If provided, it will be used instead of computing the suggestions.

`$3`

- states- Usable states for the search filter. -searchString-string- The current search string.

- searchField-string[]- Selected field to search.

- searchSuggestions-FieldWithSuggestions | FieldWithoutSuggestions | { value: '_default'; label: ''; }- Search suggestions for the selected field.

- searchQueries-SearchQuery[]- Current search queries.

- isMenuOpen-boolean- Dropdown menu open state.

- shownMenu-'fields' | 'searchSuggestions'- The type of dropdown menu currently shown.

- isFiltered-boolean- Whether the data is filtered or not.

- isInitialized-boolean- Whether the hook is initialized or not.

- actions- Actions to interact with the search filter. -clearInput-() => void- Clear the search input.

- addSearchQuery-() => void- Trigger to add the current search string and field as a search query.

- deleteSearchQuery-(idx: number) => void- Delete a search query by index.

- deleteAllSearchQueries-() => void- Delete all search queries.

- onMenuKeyDown-(e: KeyboardEvent) => void- Event handler to handle key down events on the menu.

- onSearchFieldSelect-(field: FieldWithSuggestions | FieldWithoutSuggestions | { value: '_default'; label: ''; }) => void- Event handler to handle field selection.

- onAllSearchFieldSelect-() => void- Event handler to handle "All" field selection.

- onSearchSuggestionSelect-(value: string) => void- Event handler to handle search suggestion selection.

- openMenu-() => void- Open the dropdown menu.

- closeMenu-() => void- Close the dropdown menu.

- inputProps- Props passed to the input element (search bar). -onChange-(e: ChangeEvent) => void- Event handler to handle input change.

- onKeyDown-(e: KeyboardEvent) => void- Event handler to handle key down events on the input. - Includes handling various keys:Enter, Escape, Backspace, ArrowDown, and field selection (:).

- onPaste-(e: ClipboardEvent) => void- Event handler to handle paste events on the input. - Primarily for separating search field and string.

- onFocus-() => void- Event handler to handle focus events on the input. - Used for opening the dropdown menu.

- onBlur-() => void- Event handler to handle blur events on the input.

- value-string- Same assearchString.

- ref-RefObject- Ref forwarded to the input element.

- anchorRef - Ref forwarded to the anchor element (search bar wrapper).

- listRef - Ref forwarded to the dropdown menu list element (ul).

`$3`

- field-keyof T | '_default'- The field to search.

- fieldLabel-string- The label to display.

- value-string`
- Query string to match.

Contributing

Contributions are welcome! Feel free to open an issue or submit a pull request.

Before submitting a pull request, please make sure to test your changes and update the documentation if necessary.

License

This project is licensed under the MIT License

React Multi Search

A react hook to filter data based on multiple search queries.

!NPM License
!NPM Version
!npm bundle size
!NPM Type Definitions

Features

Supported data types

_Other data types will be treated as strings._

Demo

To see the hook in action, you can check the Storybook demo.

Installation

npm:

``sh npm i react-multi-search`

yarn:

`sh yarn add react-multi-search`

`Usage`

`jsx import { useState } from 'react'; import { useMultiSearch } from 'react-multi-search';

const MyComponent = () => { const initialData = [ { name: 'John Doe', age: 20, gender: 'Male' }, { name: 'Jane Doe', age: 25, gender: 'Female' }, // ... ];

const [filteredData, setFilteredData] = useState([]);

return ( <> {/ search bar ------------------------------------------------------- /}

{/ search queries --------------------------------------------------- /} style={{ listStyle: 'none', padding: 0, }} > {searchQueries.map((query, index) => (


            
              {query.field === '_default'
                ? query.value
                :

${query.fieldLabel}: ${query.value}


        ))}
      
      
      {/ dropdown menu ---------------------------------------------------- /}
      {isMenuOpen && (
        

          
            {shownMenu === 'fields' && (
              <>
                Search by:

                
                                      onClick={onAllSearchFieldSelect}
                    disabled={searchField.value === '_default'}
                  >
                    All
                  
                

                {...props.fields.map((field) => (
                  
                                          onClick={() => onSearchFieldSelect(field)}
                      disabled={searchField.value === field.value}
                    >
                      {field.label}
                    
                  

                ))}
              
            )}
            {shownMenu === 'searchSuggestions' && (
              <>
                Search suggestions:

                {searchSuggestions?.map(
                  (value) => (
                    
                      
                    

                  )
                ) ?? No suggestions
}
              
            )}
          

        

      )}