react-fuzzy-filter

Fuzzy filter a list of data based on the search value typed in the input field. The list of matching items is made available as an argument to the FilterResults component's child function.

ReactFuzzyFilter is powered by fuse.js.

Installation

npm

npm install -S react-fuzzy-filter

yarn

yarn add react-fuzzy-filter

Example Usage

The default export of ReactFuzzyFilter is a factory function that returns two components, InputFilter and FilterResults. FilterResults receives the data typed into the InputFilter and uses it to fuzzy filter matches in its items. Each item is then rendered via a custom render function. Each invocation of the factory function creates two new "linked" components that can be used anywhere. The components do not need to live in the same component or part of the page.

import React, { Component } from "react";
import fuzzyFilterFactory, { onChangeInputValue } from "react-fuzzy-filter";

// these components share state and can even live in different components
const { InputFilter, FilterResults, changeInputValue } = fuzzyFilterFactory();

class MyComponent extends Component {
  render() {
    const items = [
      { name: "first", meta: "first|123", tag: "a" },
      { name: "second", meta: "second|443", tag: "b" },
      { name: "third", meta: "third|623", tag: "a" },
    ];
    const fuseConfig = {
      keys: ["meta", "tag"],
    };
    const setInputText = () => onChangeInputValue("hello");
    return (
      <div>
        <InputFilter debounceTime={200} />
        <div>Any amount of content between</div>
        <button onClick={setInputText}>Set Text to "hello"</button>
        <FilterResults items={items} fuseConfig={fuseConfig}>
          {filteredItems => {
            return (
              <div>
                {filteredItems.map(item => (
                  <div>{item.name}</div>
                ))}
              </div>
            );
          }}
        </FilterResults>
      </div>
    );
  }
}

changeInputValue

A function that will change the value in the input (outside of user updating InputFilter text). This is useful to trigger input value changes eg. a button that resets the InputFilter state when clicked.

// eg.
changeInputValue("new value");

Components

InputFilter

An input field that controls the state used to render the items in FilterResults.

Props

classPrefix

classPrefix is a string that is used to prefix the class names in the component. It defaults to react-fuzzy-filter. (react-fuzzy-filter__input)

initialSearch

initialSearch is an optional string that can override the initial search state when the component is created. Updating this value will also update the input value, meaning it is possible to provide the initialSearch from a value that is either async or not known until moments after the first render.

inputProps

inputProps is an object containing additional props to be passed to the input field.

onChange

onChange is an optional callback function that is called BEFORE the value in the input field changes via an onchange event. It should return a string, which will then be passed directly to FilterResults. This can be used to filter out special inputs (eg: author:jdlehman) from fuzzy searching. These special inputs could then be used to change the items being passed to FilterResults.

debounceTime

debounceTime is an optional number that denotes the time in milliseconds to debounce the onChange event on the input field. It defaults to 0.

FilterResults

Collection of fuzzy filtered items (filtered by the InputFilter's value), each being rendered by the custom render function (children prop).

Props

fuseConfig

fuseConfig is an object that specifies configuration for fuse.js, the library that is doing the fuzzy searching. The only required key in this object is keys, which is an array that specifies the key(s), in the objects to use for comparison. Check out all of the configuration options.

items

items is an array of the objects to be rendered. It defaults to an empty array.

defaultAllItems

defaultAllItems is a boolean that determines whether all items should be shown if the search value is empty. It defaults to true (meaning all items are shown by default).

prefilters

prefilters is an optional array of objects defining how to prefilter the items before they are handed off for fuzzy searching. Each object must have a regex key with a regular expression and a handler key with a callback function. Each regex match for a prefilter, will cause the corresponding handler to be called. The handler function receives the match as a string, the array of items (might be a subset if another prefilter has already happened), and the Fuse constructor function. The handler must return an array of items (probably a subset of what was passed in).

It is important to note that each match is stripped out of the search string that will be passed to the final fuzzy filtering with Fuse (after all matching prefilters have been run). This enables "commands" or special keywords to be used to filter the items, but not be used in the fuzzy search itself. Example: author:jdlehman might filter all the items that are authored by jdlehman, but the string author:jdlehman is not used to fuzzy search the filtered items. So a search with author:jdlehman mySearch could filter out all items that are not authored by jdlehman and then fuzzy search the remaining items with just mySearch.

The author prefilter described above might look like the following:

const prefilters = [
  {
    regex: /author:\S+/g,
    handler: (match, items, Fuse) => {
      const name = match.split(":")[1];
      return items.filter(item => item.author === name);
    },
  },
];

We could also define a prefilter to fuzzy search on a different key then our default Fuse config. Example: name:Bob would fuzzy filter for Bob on the name key.

const prefilters = [
  {
    regex: /\S+:\S+/g,
    handler: (match, items, Fuse) => {
      const [key, value] = match.split(":");
      const fuse = new Fuse(items, { keys: [key] });
      return fuse.search(value);
    },
  },
];