React Fuzzy Search Component

Common errors

• TypeError: Cannot read properties of undefined (reading 'map')

  cause The `list` prop provided to `FuzzySearch` is either `null`, `undefined`, or not an array.
  fix Ensure the `list` prop is always an array of objects, even if empty, before passing it to `FuzzySearch`.

• Error: Pattern length exceeds maxPatternLength

  cause The user's search query (pattern) has exceeded the configured `maxPatternLength` prop.
  fix Reduce the search query length or increase the `maxPatternLength` prop in your `FuzzySearch` component (default is 32).

• Warning: FuzzySearch: `inputProps` key `onChange` will be overridden by the internal `onChange` handler. If you wish to use your own `onChange` handler, pass it to the `onInput` prop instead.

  cause You are trying to pass an `onChange` handler via `inputProps` which conflicts with the component's internal input handling.
  fix If you need to listen to input changes, use the `onInput` prop directly on the `FuzzySearch` component instead of nesting it within `inputProps`.

• Invalid prop `resultsTemplate` supplied to `FuzzySearch`. Expected a function, got [object Object].

  cause The `resultsTemplate` prop was not provided as a function.
  fix Ensure `resultsTemplate` is a function that accepts `(props, state, styles, clickHandler)` as arguments and returns JSX.

Warnings

• breaking Version 1.0.0 introduced a breaking change by stopping the use of string refs. Ensure your React environment is compatible with modern ref patterns (callback refs or `createRef`).
  Fix: Update any legacy string refs in your codebase to modern React ref patterns if you were previously relying on them in conjunction with this library or if your React version demands it.
• gotcha The `onSelect` prop expects a function to handle the selected item. If not provided or if it doesn't correctly update component state, the UI might not reflect the selection.
  Fix: Always provide an `onSelect` prop that updates your component's local state or performs a side effect with the `newSelectedItem` argument.
• gotcha When using `resultsTemplate` for custom rendering, ensure that you correctly apply `styles` and call `clickHandler` on clickable elements within your template to maintain correct component behavior (e.g., selection highlighting and item selection).
  Fix: Refer to the `resultsTemplate` example in the documentation or quickstart to correctly implement custom rendering, paying attention to `styles.selectedResultStyle`, `styles.resultsStyle`, and `clickHandler`.
• gotcha Version 1.3.1 updated peer dependencies to explicitly support React 17 and 18. While older versions of React might still work, compatibility is best ensured with these versions.
  Fix: Ensure your project's React version is compatible with the `react-fuzzy` peer dependencies, ideally React 17 or 18. Address any peer dependency warnings during installation.
• gotcha The `maxPatternLength` prop defines the maximum length of the search query. Exceeding this length will throw an error, preventing potentially intensive search operations.
  Fix: If users are expected to type very long queries, consider increasing the `maxPatternLength` prop, but be mindful of performance implications, especially with large datasets.

Install

• npm install react-fuzzy npm
• yarn add react-fuzzy yarn
• pnpm add react-fuzzy pnpm

Imports

• FuzzySearch
  wrong:

  import FuzzySearch from 'react-fuzzy';
  const FuzzySearch = require('react-fuzzy');

  correct:

  import { FuzzySearch } from 'react-fuzzy';

  The main component, exported as a named export. ESM import is standard for React components.

Quickstart

Demonstrates basic usage of the FuzzySearch component with a predefined list of objects, including state management for selected items and an example of a custom result template for enhanced UI.

import React, { useState } from 'react';
import { FuzzySearch } from 'react-fuzzy';

function BookSearchComponent() {
  const list = [{
    id: 1,
    title: 'The Great Gatsby',
    author: 'F. Scott Fitzgerald'
  }, {
    id: 2,
    title: 'The DaVinci Code',
    author: 'Dan Brown'
  }, {
    id: 3,
    title: 'Angels & Demons',
    author: 'Dan Brown'
  }];

  const [selectedItem, setSelectedItem] = useState(null);

  return (
    <div>
      <p>Selected Book: {selectedItem ? `${selectedItem.title} by ${selectedItem.author}` : 'None'}</p>
      <FuzzySearch
        list={list}
        keys={['author', 'title']}
        width={430}
        onSelect={(newSelectedItem) => {
          setSelectedItem(newSelectedItem);
        }}
        placeholder="Search for books or authors..."
      />
      <div style={{ marginTop: '20px', borderTop: '1px solid #eee', paddingTop: '10px' }}>
        <h3>Custom Result Template:</h3>
        <FuzzySearch
          list={list}
          keys={['author', 'title']}
          width={430}
          onSelect={(newSelectedItem) => {
            setSelectedItem(newSelectedItem);
          }}
          resultsTemplate={(props, state, styles, clickHandler) => {
            return state.results.map((val, i) => {
              const style = state.selectedIndex === i ? styles.selectedResultStyle : styles.resultsStyle;
              return (
                <div
                  key={i}
                  style={{ ...style, padding: '8px', borderBottom: '1px solid #f0f0f0' }}
                  onClick={() => clickHandler(i)}
                >
                  <strong>{val.title}</strong>
                  <span style={{ float: 'right', opacity: 0.7, fontSize: '0.9em' }}>by {val.author}</span>
                </div>
              );
            });
          }}
        />
      </div>
    </div>
  );
}

export default BookSearchComponent;