React Autosuggest

WAI-ARIA compliant React autosuggest component.

Live Examples

• Basic example
  
• Custom renderer
  
• Multiple sections
• Events playground

Features

• Accessible (you can use both mouse and keyboard)
• In-memory caching (we retrive suggestions for a given input only once)
• Support for delayed requests (if request comes back after user types another letter, it will be ignored)
• You can either display a plain list of suggestions, or have multiple sections
• Full control over rendering a suggestion (you can display extra data, images, whatever you want)
• Full control over styling (we just provide the mechanics and classes for you)
• Full control over when to show the suggestions (e.g. when user types 2 or more characters)
• Ability to pass props to the input field (e.g. initial value, placeholder)
• Various events for maximum flexibility: onSuggestionSelected, onSuggestionFocused, onSuggestionUnfocused

Installation

npm install react-autosuggest --save

Basic Usage

import Autosuggest from 'react-autosuggest';

let suburbs = ['Cheltenham', 'Mill Park', 'Mordialloc', 'Nunawading'];

function getSuggestions(input, callback) {
  let regex = new RegExp('^' + input, 'i');
  let suggestions = suburbs.filter(suburb => regex.test(suburb));

  setTimeout(() => callback(null, suggestions)), 300); // Emulate API call
}

<Autosuggest suggestions={getSuggestions} />

Options

• suggestions
• suggestionRenderer
• suggestionValue
• showWhen
• onSuggestionSelected
• onSuggestionFocused
• onSuggestionUnfocused
• inputAttributes

suggestions (required)

Implement this function to tell <Autosuggest /> which suggestions to display.

function(input, callback) {
  ...
}

• input - Will be the value of the input field

• callback - Should be called once the suggestions are in hand, or error occurs.

  • Success example: callback(null, <suggestions>)
  • Error example: callback(new Error("Couldn't get locations"))

<suggestions> can have one of the following two formats:

• To display a single section with no title: [<suggestion>, <suggestion>, ...]
• To display one or more sections with optional titles: Array of objects with an optional sectionName and a mandatory suggestions keys, e.g.:

[{
  suggestions: [<suggestion>, <suggestion>]   // This section won't have a title
}, {
  sectionName: 'Second section',
  suggestions: [<suggestion>, <suggestion>, <suggestion>]
}]

<suggestion> can have one of the following two formats:

• String, e.g.: 'Mentone'
• Object, e.g.: { suburb: 'Mentone', postcode: '3194' }. This object cannot have a suggestions key. You must implement suggestionRenderer and suggestionValue in this case.

suggestionRenderer (required when suggestions are objects)

This function will be used to render the suggestion. It should return ReactElement or a string.

function(suggestion, input) {
  ...
}

• suggestion - The suggestion to render
• input - The value of the input field (e.g.: 'Men'). If user interacts using the Up or Down keys at the moment, it will be the value of the input field prior to those interactions.

For example:

function renderSuggestion(suggestion, input) { // In this example, 'suggestion' is a string
  return (                                     // and it returns a ReactElement
    <span><strong>{suggestion.slice(0, input.length)}</strong>{suggestion.slice(input.length)}</span>
  );
}

<Autosuggest suggestions={getSuggestions}
             suggestionRenderer={renderSuggestion} />

suggestionValue (required when suggestions are objects)

This function will be used to set the value of the input field when suggestion is selected. It has one parameter which is the suggestion object. This function is ignored when suggestions are strings.

For example:

function getSuggestionValue(suggestionObj) {
  return suggestionObj.suburb + ' VIC ' + suggestionObj.postcode;
}

<Autosuggest suggestions={getSuggestions}
             suggestionRenderer={renderSuggestion}
             suggestionValue={getSuggestionValue} />

showWhen (optional)

This function will be used to determine whether to show suggestions or not. It has one parameter which is the value of the input field (e.g.: 'm '). The default is:

function(input) {
  return input.trim().length > 0;
}

For example, this is how you could show suggestions only when user typed 2 or more characters:

<Autosuggest suggestions={getSuggestions}
             showWhen={input => input.trim().length >= 2} />

onSuggestionSelected (optional)

This function will be called when suggestion is selected via mouse click or Enter.

function(suggestion, event) {
  ...
}

• suggestion - The selected suggestion
• event - It can be used to call event.preventDefault() if the <Autosuggest /> is inside a form and you don't want to submit the form once user selected a suggestion using Enter.

For example:

function onSuggestionSelected(suggestion, event) {
  event.preventDefault();
  // Do other fancy stuff
}

<Autosuggest suggestions={getSuggestions}
             onSuggestionSelected={onSuggestionSelected} />

onSuggestionFocused (optional)

This function will be called when suggestion is focused via mouse hover or Up/Down keys.

function(suggestion) {
  ...
}

• suggestion - The focused suggestion

For example:

function onSuggestionFocused(suggestion) { // In this example 'suggestion' is a string
  console.log('Suggestion focused: [' + suggestion + ']');
}

<Autosuggest suggestions={getSuggestions}
             onSuggestionFocused={onSuggestionFocused} />

onSuggestionUnfocused (optional)

This function will be called when suggestion is unfocused via mouse hover, Up/Down keys, ESC key, when clicking outside <Autosuggest /> input, or when a suggestion is selected.

function(suggestion) {
  ...
}

• suggestion - The unfocused suggestion

For example:

function onSuggestionUnfocused(suggestion) { // In this example 'suggestion' is a string
  console.log('Suggestion unfocused: [' + suggestion + ']');
}

<Autosuggest suggestions={getSuggestions}
             onSuggestionUnfocused={onSuggestionUnfocused} />

inputAttributes (optional)

Hash of attributes to pass to the input field. For exampleple:

let inputAttributes = {
  id: 'locations-autosuggest',
  name: 'locations-autosuggest',
  className: 'my-sweet-locations-autosuggest',
  placeholder: 'Enter locations...',
  value: 'Mordialloc'   // Initial value
};

<label htmlFor="locations-autosuggest">Where</label>
<Autosuggest suggestions={getSuggestions}
             inputAttributes={inputAttributes} />

Styling

<Autosuggest /> comes with no styles. You can use the following classes to style it:

• react-autosuggest
• react-autosuggest__suggestions
• react-autosuggest__suggestion
• react-autosuggest__suggestion--focused
• react-autosuggest__suggestions-section
• react-autosuggest__suggestions-section-name
• react-autosuggest__suggestions-section-suggestions

An example can be found in examples/src/Autosuggest.less

The following diagrams explain the classes above.

No sections

+---| react-autosuggest |-------------------------+
|                                                 |
|  <input>                                        |
|                                                 |
|  +--| react-autosuggest__suggestions |-------+  |
|  |                                           |  |
|  |  +--| react-autosuggest__suggestion |--+  |  |
|  |  |                                     |  |  |
|  |  +-------------------------------------+  |  |
|  |                                           |  |
|  +-------------------------------------------+  |
|                                                 |
+-------------------------------------------------+

Multiple sections

+---| react-autosuggest |----------------------------------------------------+
|                                                                            |
|  <input>                                                                   |
|                                                                            |
|  +--| react-autosuggest__suggestions |----------------------------------+  |
|  |                                                                      |  |
|  |  +--| react-autosuggest__suggestions-section |--------------------+  |  |
|  |  |                                                                |  |  |
|  |  |  +--| react-autosuggest__suggestions-section-name |---------+  |  |  |
|  |  |  |                                                          |  |  |  |
|  |  |  +----------------------------------------------------------+  |  |  |
|  |  |                                                                |  |  |
|  |  |  +--| react-autosuggest__suggestions-section-suggestions |--+  |  |  |
|  |  |  |                                                          |  |  |  |
|  |  |  |  +--| react-autosuggest__suggestion |-----------------+  |  |  |  |
|  |  |  |  |                                                    |  |  |  |  |
|  |  |  |  +----------------------------------------------------+  |  |  |  |
|  |  |  |                                                          |  |  |  |
|  |  |  +----------------------------------------------------------+  |  |  |
|  |  |                                                                |  |  |
|  |  +----------------------------------------------------------------+  |  |
|  |                                                                      |  |
|  +----------------------------------------------------------------------+  |
|                                                                            |
+----------------------------------------------------------------------------+

Development

npm start

Now, open http://localhost:3000/examples/dist/index.html

Running Tests

npm test

License

MIT