React Autosuggest

Project Status

Looking for maintainers!

Unfortunately, I don't have the time to maintain this project anymore. If you are interested to help, please reach out to me on Twitter @moroshko.

Demo

Check out the Homepage and the Codepen examples.

Features

• WAI-ARIA compliant, with support for ARIA attributes and keyboard interactions
• Mobile friendly
• Plugs in nicely to Flux and Redux applications
• Full control over suggestions rendering
• Suggestions can be presented as plain list or multiple sections
• Suggestions can be retrieved asynchronously
• Highlight the first suggestion in the list if you wish
• Supports styling using CSS Modules, Radium, Aphrodite, JSS, and more
• You decide when to show suggestions (e.g. when user types 2 or more characters)
• Always render suggestions (useful for mobile and modals)
• Pass through arbitrary props to the input (e.g. placeholder, type, onChange, onBlur, or any other), or take full control on the rendering of the input (useful for integration with other libraries)
• Thoroughly tested

Installation

yarn add react-autosuggest

or

npm install react-autosuggest --save

You can also use the standalone UMD build:

<script src="https://unpkg.com/react-autosuggest/dist/standalone/autosuggest.js"></script>

Basic Usage

import React from 'react';
import Autosuggest from 'react-autosuggest';

// Imagine you have a list of languages that you'd like to autosuggest.
const languages = [
  {
    name: 'C',
    year: 1972
  },
  {
    name: 'Elm',
    year: 2012
  },
  ...
];

// Teach Autosuggest how to calculate suggestions for any given input value.
const getSuggestions = value => {
  const inputValue = value.trim().toLowerCase();
  const inputLength = inputValue.length;

  return inputLength === 0 ? [] : languages.filter(lang =>
    lang.name.toLowerCase().slice(0, inputLength) === inputValue
  );
};

// When suggestion is clicked, Autosuggest needs to populate the input
// based on the clicked suggestion. Teach Autosuggest how to calculate the
// input value for every given suggestion.
const getSuggestionValue = suggestion => suggestion.name;

// Use your imagination to render suggestions.
const renderSuggestion = suggestion => (



    {suggestion.name}



);

class Example extends React.Component {
  constructor() {
    super();

    // Autosuggest is a controlled component.
    // This means that you need to provide an input value
    // and an onChange handler that updates this value (see below).
    // Suggestions also need to be provided to the Autosuggest,
    // and they are initially empty because the Autosuggest is closed.
    this.state = {
      value: '',
      suggestions: []
    };
  }

  onChange = (event, { newValue }) => {
    this.setState({
      value: newValue
    });
  };

  // Autosuggest will call this function every time you need to update suggestions.
  // You already implemented this logic above, so just use it.
  onSuggestionsFetchRequested = ({ value }) => {
    this.setState({
      suggestions: getSuggestions(value)
    });
  };

  // Autosuggest will call this function every time you need to clear suggestions.
  onSuggestionsClearRequested = () => {
    this.setState({
      suggestions: []
    });
  };

  render() {
    const { value, suggestions } = this.state;

    // Autosuggest will pass through all these props to the input.
    const inputProps = {
      placeholder: 'Type a programming language',
      value,
      onChange: this.onChange
    };

    // Finally, render it!
    return (
      <Autosuggest
        suggestions={suggestions}
        onSuggestionsFetchRequested={this.onSuggestionsFetchRequested}
        onSuggestionsClearRequested={this.onSuggestionsClearRequested}
        getSuggestionValue={getSuggestionValue}
        renderSuggestion={renderSuggestion}
        inputProps={inputProps}
      />
    );
  }
}

Props

when multiSection={true} | Use your imagination to define how section titles are rendered. | | getSectionSuggestions | Function | ✓

when multiSection={true} | Implement it to teach Autosuggest where to find the suggestions for every section. | | renderInputComponent | Function | | Use it only if you need to customize the rendering of the input. | | renderSuggestionsContainer | Function | | Use it if you want to customize things inside the suggestions container beyond rendering the suggestions themselves. | | theme | Object | | Use your imagination to style the Autosuggest. | | id | String | | Use it only if you have multiple Autosuggest components on a page. |

suggestions (required)

Array of suggestions to display. The only requirement is that suggestions is an array. Items in this array can take an arbitrary shape.

For a plain list of suggestions, every item in suggestions represents a single suggestion. It's up to you what shape every suggestion takes. For example:

const suggestions = [
  {
    text: "Apple"
  },
  {
    text: "Banana"
  },
  {
    text: "Cherry"
  },
  {
    text: "Grapefruit"
  },
  {
    text: "Lemon"
  }
];

For multiple sections, every item in suggestions represents a single section. Again, it's up to you what shape every section takes. For example:

```js const suggestions = [ { title: "A", suggestions: [ { id: "100", text: "Apple" }, { id: "101", text: "Apricot" } ] }, { title: "B", suggestions: [ { id: "102", text: "Banana" } ] }, { title: "C", suggestions: [ {