React Autosuggest

WAI-ARIA compliant React autosuggest component.

Live Examples

• Basic example
  
• Custom renderer
  
• Multiple sections

Installation

npm install react-autosuggest --save

Basic Usage

import Autosuggest from 'react-autosuggest';

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

function getSuburbs(input, callback) {
  let regex = new RegExp('^' + input, 'i');

  setTimeout(function() {
    callback(null, suburbs.filter( suburb => regex.test(suburb) ));
  }, 300);
}

<Autosuggest suggestions={getSuburbs} />

Options

suggestions (required)

Function to get the suggestions.

function(input, callback) {
  ...
}

• input - 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, and you must implement the suggestionRenderer function to specify how to render this object.

suggestionRenderer (required when suggestions are objects)

Function that renders a single suggestion. This function shall return ReactElement or a string.

function(suggestion, input) {
  ...
}

• suggestion - The <suggestion> (string or object)
• input - The value of the input field (e.g. 'Men'). If user interacts using the Up or Down keys, it will contain the value of the input field prior to those interactions.

For example:

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

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

inputAttributes (optional)

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

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 inputAttributes={inputAttributes} suggestions={getLocations} />

Styling

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

• react-autosuggest - Component's wrapper. It includes both the input field and the suggestions list.
• react-autosuggest__suggestions - Suggestions list wrapper
• react-autosuggest__suggestions-section - Suggestions section wrapper (exists only when displaying multiple sections)
• react-autosuggest__suggestions-section-name - Suggestions section name wrapper (exists only when displaying multiple sections and sectionName is specified)
• react-autosuggest__suggestion - Single suggestion wrapper

Example: examples/src/Autosuggest.less

Development

npm start

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

License

MIT