react-search-headless

Headless React search box

Install

 
npm install --save react-search-headless
 

Example

Live example

Purpose

This repository provides a headless search component for React, alongside some out-of-the-box implementations of it.

It provides a bunch of core functions for running a search on a set of data with a host of parameters to control what is searched for, how and how it is returned. This lets you implement your search component UI exactly as you want it, and let the library take care of the search itself.

You can use pretty much any type of data for the search data, the library takes care of dealing with the different type of data, nested data, arrays and arrays of objects.

Additionally, it allows to run a search with different parameters for given entities in your data set. If you have users and teams in one dataset, you can control how a single search across the whole dataset is run differently for users and teams.

If you want a quick implementation instead, you can use the SearchBox and SearchBoxGrouped components directly, with some standard styling parameters, or the complete out-of-the-box StyledSearchBox and StyledSearchBoxGrouped

Much more to come!

Methods & props

prop: parameters

This is the core of the search, defining how you want to match the query and data.

Props

Props name	Required	Type	Description
searchKeys	false	array	If omitted, the search will run on all keys in this object. If defined, lists the keys on which the search must be run. It allows for . notation, i.e.: targeting attributes lower in the object keys tree.
searchDepth	false	number	If omitted, the search will run exhaustively through the object keys tree. Allows to define how deep in the tree you want the search to run (useful in case of massive amount of deeply nested data, to improve performance). For most cases, this can be omitted.
minCar	false	number	If omitted, the run will run from the first letter typed. Controls when to start running the search before returning results.
fuzzySensibility	false	number	Number between 0 and 1, 0 returning only exact matches, 1 returning everything. Controls the degree of fuzzy search sensitivity. Only use for fuzzy searches.
idKey	true	string	The key to use as a unique reference for each data row returned by the search.
renderName	true	function	A function that takes a returned data row from the search and outputs a human-readable name. Set it to (item) => {} if you don't want it to return anything.
renderMeta	true	function	A function that takes a returned data row from the search and outputs a metadata object. Set it to (item) => {} if you don't want it to return anything.

Implementation

const paramSearch = {
    searchKeys: ['name', 'location.address'],
    searchDepth: 2,
    minCar: 4,
    fuzzySensibility: 0.2,
    idKey:  'id',
    renderName: (item) =>  item.firstName && item.lastName,
    renderMeta: (item) =>  item,
}

method: filter()

Takes a data set, search parameters and a query then returns an array of data of the form:

[
    {
        value: `idKey provided`,
        name: `result of renderName`,
        meta: `result of renderMeta`
    },
    {
        ...
    }
]

Implementation

import { useSearch } from  'react-search-headless'
 
const MyComponent = () => {
    const { filter } = useSearch();
 
    const results = filter(data,parameters,'strict',query);
    
    {/* Do something with results */}
 
}

Props

Props name	Required	Type	Description
data	true	array	The data to run the search on. This can be any type of array, including an array of objects.
parameters	true	object	The parameters objects for the search. Defines how the search is done. See above for more details on object props.
searchType	false	string	Can be 'strict' or 'fuzzy'. Strict search will look for an exact match, but non-case sensitive. Fuzzy will rely on Fuse.js to identify a list of approximate matches.
query	true	string	The search string you are looking for.

method: filterGrouped()

Takes a data set, search parameters and a query then returns an object of the form:

{
    planets:
    {
        [
            {
                value: `idKey provided`,
                name: `result of renderName`,
                meta: `result of renderMeta`
            },
            {
                ...
            }
        ]
    },
    satellites:
    {
        [
            {
                value: `idKey provided`,
                name: `result of renderName`,
                meta: `result of renderMeta`
            },
            {
                ...
            }
        ]
    },
}

where each key in the object is one of the keys provided to searchKeys, or if omitted, the initial data object.

Implementation

import { useSearch } from  'react-search-headless'
 
const MyComponent = () => {
    const { filterGrouped } = useSearch();
 
    const results = filterGrouped(data,parameters,'strict',query);
    
    {/* Do something with results */}
 
}

Props

Props name	Required	Type	Description
data	true	object	The data to run the search on. This can be any type of object.
parameters	true	object of parameters prop	The parameters objects for the search, composed of one standard parameter prop object per key you want to search on. Defines how the search is done. See above for more details on object props. Example: parameters={planets: {searchKey: ['name'], idKey: 'id', renderName: (item) => item.name, renderMeta: (item) => item}, satellites: {searchKey: ['parent'], idKey: 'id', renderName: (item) => item.name, renderMeta: (item) => item}}
searchType	false	string	Can be 'strict' or 'fuzzy'. Strict search will look for an exact match, but non-case sensitive. Fuzzy will rely on Fuse.js to identify a list of approximate matches.
query	true	string	The search string you are looking for.

method: returnAll()

Takes a data set, return it all:

[
    {
        value: `idKey provided`,
        name: `result of renderName`,
        meta: `result of renderMeta`
    },
    {
        ...
    }
]

Implementation

import { useSearch } from  'react-search-headless'
 
const MyComponent = () => {
    const { returnAll } = useSearch();
 
    const results = returnAll(data,parameters);
    
    {/* Do something with results */}
 
}

Props

Props name	Required	Type	Description
data	true	object	The data to run the search on. This can be any type of object.
parameters	true	object	The parameters objects for the returned results. See above for more details on object props. Only uses idKey, renderName and renderMeta. All other props will be ignored.

method: returnAllGrouped()

Takes a data set, return it all:

{
    planets:
    {
        [
            {
                value: `idKey provided`,
                name: `result of renderName`,
                meta: `result of renderMeta`
            },
            {
                ...
            }
        ]
    },
    satellites:
    {
        [
            {
                value: `idKey provided`,
                name: `result of renderName`,
                meta: `result of renderMeta`
            },
            {
                ...
            }
        ]
    },
}

Implementation

import { useSearch } from  'react-search-headless'
 
const MyComponent = () => {
    const { returnAllGrouped } = useSearch();
 
    const results = returnAllGrouped(data,parameters);
    
    {/* Do something with results */}
 
}

Props

Props name	Required	Type	Description
data	true	object	The data to run the search on. This can be any type of object.
parameters	true	object of parameters prop	The parameters objects for the search, composed of one standard parameter prop object per key you want to search on. See above for more details on object props. Only uses idKey, renderName and renderMeta. All other props will be ignored.

Components

component: SearchBox

Un-styled search box that includes a suggestions list.

Implementation

import { useSearch } from  'react-search-headless'
 
const MyComponent = () => {
    const { SearchBox } = useSearch();
    
    return(
        <SearchBox
            data={dataSearchBox}
            parameters={paramsSearchBox}
            searchType='strict'
            suggestions={true}
            onFilter={(value) => {
                console.log(value)
            }}
            onSelect={(group, value) => {
                console.log(group, value)
            }}
        />
    )
}

Props

Props name	Required	Type	Description
data	true	array	The data to run the search on. This can be any type of array, including an array of objects.
parameters	true	object	The parameters objects for the search. Defines how the search is done. See above for more details on object props.
searchType	false	string	Can be 'strict' or 'fuzzy'. Strict search will look for an exact match, but non-case sensitive. Fuzzy will rely on Fuse.js to identify a list of approximate matches.
suggestions	true	boolean	Whether the search box displays a list of suggestions when returning a result.
onFilter	true	function	Callback executed whenever a search is conducted.
onSelect	true	function	Callback executed whenever an element is selected in the list of suggestions.

component: SearchBoxGrouped

Un-styled search box using grouped data and that includes a suggestions list.

Implementation

import { useSearch } from  'react-search-headless'
 
const MyComponent = () => {
    const { SearchBoxGrouped } = useSearch();
    
    return(
        <SearchBoxGrouped
            data={dataSearchBoxGrouped}
            parameters={paramsSearchBoxGrouped}
            searchType='strict'
            suggestions={true}
            onFilter={(value) => {
                console.log(value)
            }}
            onSelect={(group, value) => {
                console.log(group, value)
            }}
        />
    )
}

Props

Props name	Required	Type	Description
data	true	object	The data to run the search on. This can be any type of object.
parameters	true	object of parameters prop	The parameters objects for the search, composed of one standard parameter prop object per key you want to search on. Defined how the search is done. See above for more details on object props. Example: parameters={planets: {searchKey: ['name'], idKey: 'id', renderName: (item) => item.name, renderMeta: (item) => item}, satellites: {searchKey: ['parent'], idKey: 'id', renderName: (item) => item.name, renderMeta: (item) => item}}
searchType	false	string	Can be 'strict' or 'fuzzy'. Strict search will look for an exact match, but non-case sensitive. Fuzzy will rely on Fuse.js to identify a list of approximate matches.
suggestions	true	boolean	Whether the search box displays a list of suggestions when returning a result.
onFilter	true	function	Callback executed whenever a search is conducted.
onSelect	true	function	Callback executed whenever an element is selected in the list of suggestions.

component: StyledSearchBox

Fully-styled search box that includes a suggestions list.

Implementation

import { useSearch } from  'react-search-headless'
 
const MyComponent = () => {
    const { StyledSearchBox } = useSearch();
    
    return(
        <StyledSearchBox
            data={dataSearchBox}
            parameters={paramsSearchBox}
            searchType='strict'
            suggestions={true}
            variant={variant}
            fontSize={fontSize}
            height={height}
            width={width}
            placeholder={placeholder}
            onFilter={(value) => {
                console.log(value)
            }}
            onSelect={(group, value) => {
                console.log(group, value)
            }}
        />
    )
}

Props

Props name	Required	Type	Description
data	true	array	The data to run the search on. This can be any type of array, including an array of objects.
parameters	true	object	The parameters objects for the search. Defines how the search is done. See above for more details on object props.
searchType	false	string	Can be 'strict' or 'fuzzy'. Strict search will look for an exact match, but non-case sensitive. Fuzzy will rely on Fuse.js to identify a list of approximate matches.
suggestions	true	boolean	Whether the search box displays a list of suggestions when returning a result.
onFilter	true	function	Callback executed whenever a search is conducted.
onSelect	true	function	Callback executed whenever an element is selected in the list of suggestions.
variant	false	string	One of light or dark. Changes the overall style to dark or light mode. By default, light.
height	false	number	Search box height in vh. By default, auto.
width	false	number	Search box width in vw. By default, auto.
fontSize	false	number	Font size in px. By default, auto.
placeholder	false	string	Search box placeholder text. By default, empty.

component: StyledSearchBoxGrouped

Fully-styled search box using grouped data and that includes a suggestions list.

Implementation

import { useSearch } from  'react-search-headless'
 
const MyComponent = () => {
    const { StyledSearchBoxGrouped } = useSearch();
    
    return(
        <StyledSearchBoxGrouped
            data={dataSearchBoxGrouped}
            parameters={paramsSearchBoxGrouped}
            searchType='strict'
            suggestions={true}
            variant={variant}
            fontSize={fontSize}
            height={height}
            width={width}
            placeholder={placeholder}
            onFilter={(value) => {
                console.log(value)
            }}
            onSelect={(group, value) => {
                console.log(group, value)
            }}
        />
    )
}

Props

Props name	Required	Type	Description
data	true	object	The data to run the search on. This can be any type of object.
parameters	true	object of parameters prop	The parameters objects for the search, composed of one standard parameter prop object per key you want to search on. Defined how the search is done. See above for more details on object props. Example: parameters={planets: {searchKey: ['name'], idKey: 'id', renderName: (item) => item.name, renderMeta: (item) => item}, satellites: {searchKey: ['parent'], idKey: 'id', renderName: (item) => item.name, renderMeta: (item) => item}}
searchType	false	string	Can be 'strict' or 'fuzzy'. Strict search will look for an exact match, but non-case sensitive. Fuzzy will rely on Fuse.js to identify a list of approximate matches.
suggestions	true	boolean	Whether the search box displays a list of suggestions when returning a result.
onFilter	true	function	Callback executed whenever a search is conducted.
onSelect	true	function	Callback executed whenever an element is selected in the list of suggestions.
variant	false	string	One of light or dark. Changes the overall style to dark or light mode. By default, light.
height	false	number	Search box height in vh. By default, auto.
width	false	number	Search box width in vw. By default, auto.
fontSize	false	number	Font size in px. By default, auto.
placeholder	false	string	Search box placeholder text. By default, empty.

Usage

### Simple search box

import React, { useState } from 'react'
import  { useSearch }  from  'react-search-headless'
 
const  MyComponent = () => {
 
    const [results, setResults] = useState();
    const { filter } = useSearch();
 
    const data = {...}
    const paramsSearch = {
        idKey: 'id',
        renderName: (item) =>  item.firstName && item.lastName,
        renderMeta: (item) =>  item,
    }
    
    return(
    <input
        placeholder='Search anything...'
        onChange={({ target: { value } }) =>
            setResults(
                filter(data,paramsSearch, 'strict', value)
            )}
    />
    {results &&
    results.length > 0 &&
    results.map((item, index) => (
        <p  key={index}>{JSON.stringify(item.metadata)}</p>
    ))}
}
 

Simple search box with named keys

import React, { useState } from 'react'
import  { useSearch }  from  'react-search-headless'
 
const  MyComponent = () => {
 
    const [results, setResults] = useState();
    const { filter } = useSearch();
 
    const data = {...}
    const paramsSearch = {
        searchKeys: ['lastName'], // We are only searching on lastName
        idKey: 'id',
        renderName: (item) =>  item.firstName && item.lastName,
        renderMeta: (item) =>  item,
    }
    
    return(
    <input
        placeholder='Search anything...'
        onChange={({ target: { value } }) =>
            setResults(
                filter(data,paramsSearch, 'strict', value)
            )}
    />
    {results &&
    results.length > 0 &&
    results.map((item, index) => (
        <p  key={index}>{JSON.stringify(item.metadata)}</p>
    ))}
}
 

Simple search box with search depth

import React, { useState } from 'react'
import  { useSearch }  from  'react-search-headless'
 
const  MyComponent = () => {
 
    const [results, setResults] = useState();
    const { filter } = useSearch();
 
    const data = {...}
    const paramsSearch = {
        searchDepth: 2, // We are only searching to a depth of 2 levels across all keys, 
        //i.e.: ignoring an attribute such as data.location.address.formatted_address
        idKey: 'id',
        renderName: (item) =>  item.firstName && item.lastName,
        renderMeta: (item) =>  item,
    }
    
    return(
    <input
        placeholder='Search anything...'
        onChange={({ target: { value } }) =>
            setResults(
                filter(data,paramsSearch, 'strict', value)
            )}
    />
    {results &&
    results.length > 0 &&
    results.map((item, index) => (
        <p  key={index}>{JSON.stringify(item.metadata)}</p>
    ))}
}
 

Grouped filter search box with complex search parameters

import React, { useState } from 'react'
import  { useSearch }  from  'react-search-headless'
 
const  MyComponent = () => {
 
    const [results, setResults] = useState();
    const { filterGrouped } = useSearch();
 
    const data = {...}
    const paramsSearch = {
        planets: {
            searchDepth: 2,
            idKey: 'id',
            renderName: (item) =>  item.name,
            renderMeta: (item) =>  item,
        },
        satellites: {
            searchKeys: ['name','parent.name','mass'],
            idKey: 'id',
            renderName: (item) =>  item.name && ', satellite of ' && item.parent.name,
            renderMeta: (item) =>  item,
        }
    }
    
    return(
    <input
        placeholder='Search anything...'
        onChange={({ target: { value } }) =>
            setResults(
                filterGrouped(data,paramsSearch, 'strict', value)
            )}
    />
    {results && (
    <div>
        {Object.keys(results).map((item, index) => {
            return (
            <div>
                <div  key={index}>
                    <h1>{item}</h1>
                <div>
                {results[item].length > 0 &&
                    results[item].map((itemResult, indexResult) => (
                        <div
                            key={indexResult}
                            onClick={() => {
                                console.log(JSON.stringify(itemResult))								
                                setResults(null)
                            }}
                        >
                            <p>{itemResult.name}</p>
                        </div>
                ))}
                {results[item].length === 0 && <p>No results</p>}
            </div>
    </div>)
 

Dependencies

This repository relies on the brilliant library Fuse.js for the fuzzy-search logic.

License

MIT © GwenhaelG