react-structured-query-search-suggestions 🎉

react-structured-query-search-suggestions is a javascript library that provides autocomplete search queries with dynamic/static suggestions. This was inspired by visualsearch, react-structured-filter and react-structured-query-search.

This plugin is written on top of react-structured-filter, which has been revamped to add React 16 support and the existing code has been overriden to support New features.

You can use all the react-typeahead, react-structured-filter API(options) as they are.

🎉🎊 Features 🎊🎉

Allows user to search without any category & operator (Free text search) for maximum of one search term
Ajax support to retrieve values incrementally as the user types
Allows user to send values for Category in Array<String> or Array<Object>
Allows user to pass custom loader component.
Allows user to customize the header of dropdown (categories, operators, values).
Allows user to enable/disable operators in search.
Allows user to perform category-value search without operator (if isAllowOperator is false).
Switch between unique/duplicate categories (key).
Switch between unique/duplicate values
Allows user to send custom operators list.
Allows user to render custom tag(token) Component or the tag(token) Item.
Allows user to update Options(props) at runtime.
Allows user to set date with time (hh mm ss)

Install

npm install --save react-structured-query-search-suggestions

Usage (Example Code) (Demo)

If you want to use Tokenizer then you either import as follows:

import ReactStructuredQuerySearch from "react-structured-query-search-suggestions";
import "react-structured-query-search-suggestions/dist/index.css";

or

import {Tokenizer} from "react-structured-query-search-suggestions";
import "react-structured-query-search-suggestions/dist/index.css";

If you want to use Typeahead then you have to import as follows:

import {Typeahead} from "react-structured-query-search-suggestions";
import "react-structured-query-search-suggestions/dist/index.css";

API

New flexible modification/existing options

Parameter	Type	Default	Description
options	`Array`	[]	An array supplied to the filter function.
maxVisible	`Number`		Limit the number of options rendered in the results list.
customClasses	`Object`		Allowed Keys: `input` `results` `listItem` `listAnchor` `hover` `typeahead` `resultsTruncated` `token` An object containing custom class names for child elements. Useful for integrating with 3rd party UI kits.
placeholder	`String`		Placeholder text for the typeahead input.
🆕 disabled	`Boolean`	`false`	Set to `true` for disabling the StructureQuerySearch
🆕 defaultSelected	`function, Array`	`[]`	Allows user to initialize the search with selected values (Include isAllowFreeSearch:true in the free search term selected option)
🆕 categoryHeader	`String, Component`	`"Category"`	Allows user the change the header title of `Category`
🆕 clickToEditToken	`Boolean`	`false`	Allows user to `edit` the selected token by clicking on it
🆕 operatorHeader	`String, Component`	`"Operator"`	Allows user the change the header title of `Operator`
🆕 valueHeader	`String, Component`	`"Value"`	Allows user the change the header title of `Value`
🆕 isAllowSearchDropDownHeader	`Boolean`	`"true"`	Allows user to `enable/disable` search drop-down header
🆕 isAllowOperator	`Boolean`	`false`	Allows user to `enable/disable` operators in search
🆕 isAllowClearAll	`Boolean`	`true`	Allows user to clear all selected data
onTokenRemove	`Function`		Event handler triggered whenever a token is removed.
onTokenAdd	`Function`		Event handler triggered whenever a token is added. Params: `(addedToken)`
🆕 onClearAll	`function`		Event handler triggered whenever clear all button clicked
onOptionSelected	`Function`		Event handler triggered whenever a user picks an option.
🆕 updateOptions	`function`		Allows user to update the Options(props) at runtime, this function is called before `onTokenRemove` and `onTokenAdd`
🆕 fuzzySearchEmptyMessage	`String`	`"No result found"`	This message is shown when dropdown doesn't have search value
🆕 renderLoading	`function, Component`	`"Loading...."`	Show custom loader when values are retrieved using Ajax
🆕 renderTokens	`function`		Allows user to render custome Token Component
🆕 renderTokenItem	`function`		Allows user to render custome Token Item
🆕 renderSearchItem	`function`		Allows user to render custome value
🆕 fetchData	`function`	[]	Allows user to fetch dynamic suggestions(options). (Required if any of the options has `type:"textoptions"` and `dynamicOptions:true`)
onKeyDown	`Function`		Event handler for the `keyDown` event on the typeahead input.
onKeyPress	`Function`		Event handler for the `keyPress` event on the typeahead input.
onKeyUp	`Function`		Event handler for the `keyUp` event on the typeahead input.
onBlur	`Function`		Event handler for the `blur` event on the typeahead input.
onFocus	`Function`		Event handler for the `focus` event on the typeahead input.

props.options (Data attributes)

Parameter	Type	Default	Required	Description
category	`String`		`required`	Name of the first thing the user types.
type	`String`	`text`		This can be one of the following: text: Arbitrary text for the value. No autocomplete options. Operator choices will be: "=", "!=", "contains", "!contains". textoptions: You must additionally pass an `options` value. Operator choices will be: "=", "!=". number: Arbitrary text for the value. No autocomplete options. Operator choices will be: "=", "!=", "<", "<=", ">", ">=". date: Shows a calendar and user can choose date and time.". Operator choices will be: "=", "!=", "<", "<=", ">", ">=".
🆕 operator	`Array, function`		required, if `isAllowOperator` prop is set to `true`	If this attribute is added then it would ignore the type check as described in `type` parameter and it would accept what you have passed
options	`Array`		`required, if type="textoptions"`	Get the value according to selected category
dynamicOptions	`Boolean`	false		A boolean which if set to true, dynamic search suggestions(options) will be loaded using fetchData function. If set to false, static options will be served
🆕 isAllowCustomValue	`Boolean`	`false`		When this parameter is set to `true`, it allows you to send multiple custom values for `type=textoptions`
🆕 isAllowDuplicateCategories	`Boolean`	`true`		Switch between `unique/duplicate` categories (key)
🆕 isAllowDuplicateOptions	`Boolean`	`false`		Switch between `unique/duplicate` values
🆕 fuzzySearchKeyAttribute	`String`	`name`		If Category (options)values are `Array<Object>` then By default fuzzy search look for `name` attribute inside options(values) but you can change that attribut lookup key using `fuzzySearchKeyAttribute`

How to Contribute

Setting Up

Please run npm install in the root and example folders. then do the following:

Go to root folder and run npm start after this
Go to example folder and run npm run link (only for first time)
Go to example folder and run npm start it would run the plugin from link which we have created.

Now, anytime you make a change to your library in src/ or to the example app's example/src create-react-app will live-reload your local dev server so you can iterate on your component in real-time.

License

MIT

acreto / react-structured-query-search-suggestions Goto Github PK