react-structured-search

Overview

A React, Typescript library for quickly intergrate autocomplete search queries with dynamic suggestions.

👉 Demo: https://react-structured-search.quang.work/?path=/docs/react-structured-search--demo

Table of Contents

• Features
• Install
• Usage
• Types

Features

• 🔥 Performance optimized
• 🔥 Typescript supported
• 🔥 Dynamic typeahead suggestion with passed in callbacks
• 🔥 Easy to customize

Install

npm install react-structured-search

or

yarn add react-structured-search

Usage

Simple use like this:

import { StructuredSearch } from "@data-platform/structured-search";

...

<StructuredSearch
  filters={MOCK_FILTERS}
  dropdownStyle={{ maxWidth: 400 }}
  onSubmit={(rs) => console.log("Search result:", rs)}
/>

The example mockFilter() function:

// START mock
export const mockAsyncFunction = (
  obj: Option[],
  delay = 500,
): Promise<Option[]> =>
  new Promise((resolve) => {
    setTimeout(() => {
      resolve(obj);
    }, delay);
  });

export const getRandomNumberBetween = (min: number, max: number) =>
  Math.floor(Math.random() * (max - min + 1) + min);

export const getRandomItemNameOptions = (name: string) => {
  const result: string[] = [];
  const numItems = getRandomNumberBetween(3, 10); // Generate a random number of items between 0 and 9

  // eslint-disable-next-line no-plusplus
  for (let i = 0; i < numItems; i++) {
    const randomNumber = Math.floor(Math.random() * 1000); // Generate a random number between 0 and 999
    result.push(`${name} ${randomNumber}`);
  }

  return result.map((x) => ({ value: x, name: x }) as Option);
};

const OPERATORS = {
  Equal: {
    value: "=",
    name: "=",
    subText: "is",
  },
  NotEqual: {
    value: "!=",
    name: "!=",
    subText: "is not",
  },
};

const authorFilter = {
  value: "author",
  name: "Author",
  icon: <UserOutlined />,
  subText: "By an author account or email",
  tagColor: "cyan",
  operators: [OPERATORS.Equal],
};

export const MOCK_FILTERS: Filter[] = [
  {
    value: "atrributes",
    name: "Attributes",
    icon: <CodeSandboxOutlined />,
    subText: "Search for attributes",
    tagColor: "#F09801",
    disableTooltip: { title: "Disabled because..." },
    children: [
      {
        value: "domain",
        name: "Domain",
        icon: <GlobalOutlined />,
        subText: "In a domain",
        tagColor: "green",
        disableTooltip: { title: "Disabled because Namespace existed" },
        operators: [OPERATORS.Equal, OPERATORS.NotEqual],
        options: async (searchText) =>
          mockAsyncFunction(getRandomItemNameOptions("Domain")),
      },
      authorFilter,
    ],
  },
  {
    value: "segments",
    name: "Segments",
    icon: <ExperimentOutlined />,
    subText: "Search for segments",
    tagColor: "#F09801",
    disableTooltip: { title: "Disabled because..." },
    children: [
      {
        value: "namespace",
        name: "Namespace",
        icon: <SafetyOutlined />,
        subText: "In a namespace",
        tagColor: "green",
        disableTooltip: { title: "Disabled because Domain existed" },
        operators: [OPERATORS.Equal, OPERATORS.NotEqual],
        options: async (searchText) =>
          mockAsyncFunction(getRandomItemNameOptions("Namespace")),
      },
      authorFilter,
    ],
  },
  authorFilter,
];
// END mock

Types

StructuredSearchProps	Type	Description
filters	Filter[]	Filters configuration
value	StructuredSearchValue[]	Current value
defaultValue	StructuredSearchValue[]	Default value when init
onSubmit	(result: StructuredSearchValue[]) => void	Handle pressing Enter or submit
onChange	(values: string[]) => void	Handle changing box values
onBlur	FocusEventHandler	Handle box lossing focus
onInputKeyDown	KeyboardEventHandler	Handle box's input keying down
clearAfterSearch	boolean	Clear the input after pressing Enter or submit
width	number or string	Width of the search box
height	number or string	Height of the search box
prefixIcon	ReactNode	Custom prefix icon
defaultFilterKey	string	Default added filter after user enters text only ( Filter's values )
...rest	AntDesignSelectProps	All props of Ant Design's Select component

Filter	Type	Description
operators	Option[]	Operators configuration
typeaheadCallback	(searchText: string) => Promise<Option[]>	API callback when user finish typing search text ( debounced )
tagColor	AntDesignTagColorProp	Colors supported by Ant Design's Tag component
hasMultiOptions	boolean	Enable selecting multiple options
...rest	Option	All props of Option type

StructuredSearchValue	Type	Description
filterKey	string	Filter key value of a filter tag
operatorKey	string	Operator value of a filter tag
value	string	Search value of a filter tag

Option	Type	Description
value	string	Value of the option
name	string	Label of the option
icon	ReactNode	Icon of the option
subText	string	Description of the option
optionRender	(option: Option) => ReactNode	Custom content of the option
hidden	(selectedValues: string[]) => boolean;	Hide the option, selectedValues is the box's current values
disabled	(selectedValues: string[]) => boolean;	Disable the option, selectedValues is the box's current values
disableTooltip	AntDesignTooltipProps	Tooltip of the option when disabled