Skip to content

Latest commit

 

History

History
171 lines (138 loc) · 6.81 KB

README.md

File metadata and controls

171 lines (138 loc) · 6.81 KB
Raw

React Search Dialog 🔎 Version NPM bundle size

A batteries included search component that aims to make implementing a modern search experience in your app as easy as possible.

With a focus on performance and not reinventing the wheel, React Search Dialog is built on top of battle tested libraries Fuse.js and react-window so that no matter the item list, you'll get the results you're looking for near instantly with no bloat to your DOM!

Table of Contents

Installation

npm

npm install react-search-dialog

yarn

yarn add react-search-dialog

pnpm

pnpm add react-search-dialog

Features

  • ✅ Handles massive data sets with ease
  • ✅ Live results as you type
  • ✅ Out of the box styling, with ability to customize as needed
  • ✅ Mobile friendly
  • ✅ Optional render functions for search results and recent items
  • ✅ Built in recent search history (with ability to disable)
  • ✅ Optional quick select section for common search items (fully customizable)

Examples

A couple of examples to show how simple react-search-dialog is to use.

Basic Usage

Getting started with react-search-dialog is super simple! The minimum you need to get up and running is:

import { Search } from 'react-search-dialog';

type User = {
  id: string;
  name: string;
  // A label property is required if not using a string array as your item list!
  label: string;
};

const items: User[] = [
  { id: '1', label: 'Item 1', name: 'Justin' },
  { id: '2', label: 'Item 2', name: 'Nick' },
  { id: '3', label: 'Item 3', name: 'Dan' },
  { id: '4', label: 'Item 4', name: 'Adam' },
  { id: '5', label: 'Item 5', name: 'Caleb' },
];

const App = () => {
  return (
    <Search items={items} onItemSelect={(item) => console.log(item.label)} />
  );
};

Customizing Search Results

In most cases, you'll want to customize the look and feel of your search results to conform to your existing site styling. You can acomplish that by utilizing the renderResult prop. The same can be done for recent items by using the renderRecent prop as well!

Here's a quick example of how you might customize your search results:

import { useCallback } from 'react';
import { Search, RenderItemArgs } from 'react-search-dialog';

type CoffeeItem = {
  id: string;
  imgUrl: string;
  // A label property is required if not using a string array as your item list!
  label: string;
};

const items: CoffeeItem[] = [
  { id: '1', label: 'Latte', imgUrl: 'example.com/latte.png' },
  { id: '2', label: 'Macchiato', imgUrl: 'example.com/macchiiato.png' },
  { id: '3', label: 'Cappuccino', imgUrl: 'example.com/cappuccino.png' },
  { id: '4', label: 'Cold Brew', imgUrl: 'example.com/coldbrew.png' },
  { id: '5', label: 'Affogato', imgUrl: 'example.com/affogato.png' },
];

const renderResult = useCallback(
  ({ item, smallDisplay, closeDialog, addToRecents }: RenderItemArgs<Client>) => (
    <div
      onClick={() => {
        // Adds the item to the recent search history
        // if `noHistory` is not set to true.
        addToRecents();
        // Clsoes the search dialog.
        closeDialog();
      }}
      style={{
        // Since we're utilizing react-window, it might be a good idea
        // to set a fixed height on your result items in some circumstances.
        height: '100',
      }}
    >
      {/* If the display is small, we'll only show the label */}
      {smallDisplay ? item.label : (
        <div style={{ display: 'flex', alignItems: 'center' }}>
          <img src={item.imgUrl} alt={item.label} />
          <h3>{item.label}</h3>
        </div>
      )}
    </div>
  ),
  []
);

const App = () => {
  return (
    <Search
      items={items}
      itemHeight={100}
      onItemSelect={(item) => console.log(item)}
      renderResult={renderResult}
    />
  );
};

Props

Below is a table of all props offered by the Search component. The majority of this table is a pared down, more digestible version of the exported type SearchProps so if more detail is needed, please feel free to refer to the type definitions directly!

Key
✅ Required
⚠ Conditionally Optional
❌ Optional
Required Prop Name Prop Type Description
✅ items Array of T (generic) The items to search through. IMPORTANT: T must have a label property OR be a string.
⚠ onItemSelect (item: T) => void Callback to fire when an item is selected. IMPORTANT: When NOT passing in your own render function with renderResult, this prop is required so that an action can be taken on search result / recent click.
❌ buttonProps ButtonProps OR (isSmallScreen: boolean) => ButtonProps Props to pass to the button that opens the search dialog. Click here to read more about the props available to the Button component
❌ placeholder string The placeholder text to display in the search input
❌ quickFillTitle string The title used for the quick fill section of the search dialog
❌ itemHeight number or ItemHeightPreset Height of each item in the search results
❌ quickFillItems Array of T (generic) Items to display in the quick fill section
❌ maxHeight string or number Maximum height of the search dialog
❌ maxWidth string or number Maximum width of the search dialog
❌ noHistory boolean Whether or not to record or display recent search history
❌ renderResult ({ item, smallDisplay, closeDialog, addToRecents }) => JSX.Element Callback to render a single search result IMPORTANT: Because you're supplying the render function for each search result, it's up to you to use the addToRecents function when a selection is made by the user, and the closeDialog function when you see it appropriate for the search dialog to close.
❌ renderRecent ({ item, smallDisplay, closeDialog, addToRecents }) => JSX.Element Callback to render a single recent search item IMPORTANT: Because you're supplying the render function for each recent search item, it's up to you to use the addToRecents function when a selection is made by the user, and the closeDialog function when you see it appropriate for the search dialog to close.