react-autosuggest

To run the project's demo environment for development and testing, install the dependencies and start the development server using npm. Once running, you can view the demo at http://localhost:3000/demo/dist/index.html.

npm install
npm start

You can install react-autosuggest using npm or yarn, or use the standalone UMD build via a script tag.

yarn add react-autosuggest

npm install react-autosuggest --save

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

If you render multiple Autosuggest components on a single page, you must provide a unique id prop to each one. This is required for the component to correctly set ARIA attributes for accessibility.

<Autosuggest id="source" ... />
<Autosuggest id="destination" ... />

To display suggestions in multiple sections with titles, set multiSection={true}. When using this mode, you must implement two additional props:

1. renderSectionTitle: Defines how section titles are rendered. Signature: (section) => string | ReactElement.
2. getSectionSuggestions: Defines where to find the suggestions for a specific section. Signature: (section) => Array.

Example suggestion structure for multiSection:

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

Autosuggest uses react-themeable. You can provide a theme object to map component parts to your own CSS classes. If no theme is provided, it defaults to classes prefixed with react-autosuggest__.

Default theme keys:

• container / containerOpen
• input / inputOpen / inputFocused
• suggestionsContainer / suggestionsContainerOpen
• suggestionsList
• suggestion / suggestionFirst / suggestionHighlighted
• sectionContainer / sectionContainerFirst
• sectionTitle

To prevent the page from scrolling when the suggestions container reaches its scroll boundaries, wrap the container in react-isolated-scroll. You must intercept the ref from containerProps and pass the isolatedScroll.component to the original ref via the renderSuggestionsContainer prop.

import IsolatedScroll from 'react-isolated-scroll';

function renderSuggestionsContainer({ containerProps, children }) {
  const { ref, ...restContainerProps } = containerProps;
  const callRef = isolatedScroll => {
    if (isolatedScroll !== null) {
      ref(isolatedScroll.component);
    }
  };

  return (
    <IsolatedScroll ref={callRef} {...restContainerProps}>
      {children}
    </IsolatedScroll>
  );
}

<Autosuggest renderSuggestionsContainer={renderSuggestionsContainer} ... />

The input element is exposed on the Autosuggest instance via the input property. To access it, use a ref callback to capture the instance and store the input property.

function storeInputReference(autosuggest) {
  if (autosuggest !== null) {
    this.input = autosuggest.input;
  }
}

<Autosuggest ref={storeInputReference} ... />

Since Autosuggest is a controlled component, you must provide an onChange handler within inputProps. The handler receives the event and an object describing how the change occurred.

Possible method values:

• 'down': User pressed Down key.
• 'up': User pressed Up key.
• 'escape': User pressed Escape.
• 'enter': User pressed Enter.
• 'click': User clicked/tapped a suggestion.
• 'type': User typed, pasted, or used backspace.

Use renderSuggestionsContainer to customize the container wrapping the suggestions (e.g., adding custom text or controlling scrolling).

Important: You must pass containerProps to the topmost element returned. If you return a composite component (like IsolatedScroll), you must call containerProps.ref with the topmost element's ref.

Signature: ({ containerProps, children, query }) => ReactElement

function renderSuggestionsContainer({ containerProps, children, query }) {
  return (
    <div {...containerProps}>
      {children}
      <div>
        Press Enter to search <strong>{query}</strong>
      </div>
    </div>
  );
}