nanchenchen / react-simple-autocomplete

Redux Simple Autocomplete

Simple, customizable, unopinionated autocomplete wrapper for React.

Installation

npm:

$ npm install --save react-simple-autocomplete

npmcdm:

<!-- <SimpleAutocomplete /> -->
<script src="//npmcdn.com/react-simple-autocomplete"></script>

Demo

bendyorke.github.io/react-simple-autocomplete

What does this library try to solve?

Autocomplete fields are very common but can be a pain to write. When looking around, all the available autocomplete fields were either incomplete, or very opinionated. I wanted a reusable component to provide me the basic functionality but could be taylored to any use case.

Basic output

Given:

<Autocomplete items={['one', 'two']} />

Output with menu closed:

<div>
  <input type="text" />
</div>

Output with menu open & first item highlighted:

<div>
  <input type="text" />
  <ul>
    <em><li>one</li></em>
    <li>two</li>
  </ul>
</div>

API

<Autocomplete />

Children:

<Autocomplete /> can accept a single element as a child. This element can contain nested elements, however the top level element must respond to #value. Any refs applied to the top level child will be overridden, however it can be accessed via #input. Defaults to: <input type="text" />

NOTE: Currently, onMouseDown, onMouseEnter, and onClick are overwritten on the top level child element. This should be fixed shortly. onChange, however, is free to be used!

Methods:

#open

Opens the menu

#close

Closes the menu

.input

Retrieve the top level child

.options

Retrieve the items that are currently available as options

Props:

defaultInputValue: [Any]

Default input value. It is set to be an empty string by default.

items: [Any]

The items prop is an array the different possible matches. It can be an array of any type, however only strings are supported by the default filter prop.

filter: (item: Any, query: String) -> Boolean

Filter function to decide which items are possible choices. Called on each item individually and is passed the current item & the value of the input field. Defaults to:

(item, query) => item.toLowerCase().includes(query.toLowerCase())

sort: (a: Any, b: Any) -> Number

Sort function to be called on the remaining items after the filter function. Defaults to no sort (() => {}).

Can also pass undefined, null, or false to use the default Array.sort() method.

limit: Number

Limit your results to a specific number. Defaults to undefined.

submitOnSelect: bool

Whether onSubmit will be called when an item is selected. The default is true.

onlyAllowsValueInItems: bool

Whether the input is restricted to vaule in items. The default is false.

renderMenu: ({items: [Any]}) -> Element

Function used to render the menu. Gives you full control to style your menu, use whichever elements you want, nest the items, group the items, etc, etc. Items are passed as named parameters to support stateless functional components. Defaults to:

({items}) => <ul>{items}</ul>

renderItem: ({item: Any, highlighted: Boolean}) -> Element

Function used to render each individual item. Gives you full control to style your item, apply conditional logic if the item is highlighted, and mutate the items display value. Items are passed as named parameters to support stateless functional components. Defaults to:

({item, highlighted}) => highlighted
  ? <em><li>{items}</li></em>
  : <li>{items}</li>

onSelectItem: ({item: Any, event: React.SyntheticEvent}) -> Any

Callback called when an item is selected (either onClick, or onKeyDown: Enter when an element is highlighted).

The input value will be updated to the selected item value no matter this function is defined or not.

onChange: (event: React.SyntheticEvent, value: [Any]})

Callback function of the input field

onSubmit: (value: [Any]})

Callback function when user hit Enter key. It will also be triggered if submitOnSelect is true.

onFocus: ({event: React.SyntheticEvent}) -> Any

Menu is opened when input element is focused prior to the onFocus handler being invoked.

onBlur: ({event: React.SyntheticEvent}) -> Any

Menu is closed when the input element is blurred prior to the onBlur handler being invoked.

NOTE: This is not called when an item is selected from the menu.

Tests

Tests are run with mocha, and written in chai & sinon. Any test related code is located alonside project files nested under a __tests__ directory. Files containing tests to be run should be postfixed with -tests.js.