Repository files navigation

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.

React-Autosuggest Bot will help you understand this repository better. You can ask for code examples, installation guide, debugging help and much more.

Check out theHomepage and theCodepen examples.

• WAI-ARIA compliant, with support for ARIA attributes and keyboard interactions
• Mobile friendly
• Plugs in nicely to Flux andRedux applications
• Full control oversuggestions rendering
• Suggestions can be presented asplain list ormultiple sections
• Suggestions can be retrievedasynchronously
• Highlight the first suggestion in the list if you wish
• Supports styling usingCSS Modules,Radium,Aphrodite,JSS,and more
• You decidewhen 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), ortake full control on the rendering of the input (useful for integration with other libraries)
• Thoroughly tested

yarn add react-autosuggest

or

npm install react-autosuggest --save

You can also use the standalone UMD build:

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

importReactfrom'react';importAutosuggestfrom'react-autosuggest';// Imagine you have a list of languages that you'd like to autosuggest.constlanguages=[{name:'C',year:1972},{name:'Elm',year:2012},  ...];// Teach Autosuggest how to calculate suggestions for any given input value.constgetSuggestions=value=>{constinputValue=value.trim().toLowerCase();constinputLength=inputValue.length;returninputLength===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.constgetSuggestionValue=suggestion=>suggestion.name;// Use your imagination to render suggestions.constrenderSuggestion=suggestion=>(<div>{suggestion.name}</div>);classExampleextendsReact.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.constinputProps={placeholder:'Type a programming language',      value,onChange:this.onChange};// Finally, render it!return(<Autosuggestsuggestions={suggestions}onSuggestionsFetchRequested={this.onSuggestionsFetchRequested}onSuggestionsClearRequested={this.onSuggestionsClearRequested}getSuggestionValue={getSuggestionValue}renderSuggestion={renderSuggestion}inputProps={inputProps}/>);}}

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

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

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

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

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

This function will be called every time you might need to updatesuggestions. It has the following signature:

functiononSuggestionsFetchRequested({ value, reason})

where:

• value - the current value of the input
• reason - string describing whyonSuggestionsFetchRequested was called. The possible values are:
  • 'input-changed' - user typed something
  • 'input-focused' - input was focused
  • 'escape-pressed' - user pressedEscape to clear the input (and suggestions are shown for empty input)
  • 'suggestions-revealed' - user pressedUp orDown to reveal suggestions
  • 'suggestion-selected' - user selected a suggestion whenalwaysRenderSuggestions={true}

This function will be called every time you need to clearsuggestions.

All you have to do in this function is to setsuggestions to[].

Note: WhenalwaysRenderSuggestions={true}, you don't have to implement this function.

When user navigates the suggestions using theUp andDown keys,the input value should be set according to the highlighted suggestion. You design how suggestion is modelled. Therefore, it's your responsibility to tell Autosuggest how to map suggestions to input values.

This function gets the suggestion in question, and it should return a string. For example:

functiongetSuggestionValue(suggestion){returnsuggestion.text;}

Use your imagination to define how suggestions are rendered.

The signature is:

functionrenderSuggestion(suggestion,{ query, isHighlighted})

where:

• suggestion - The suggestion to render
• query - Used to highlight the matching string. As user types in the input,query will be equal to the trimmed value of the input. Then, if user interacts using theUp orDown keys,the input will get the value of the highlighted suggestion, butquery will remain to be equal to the trimmed value of the input prior to theUp andDown interactions.
• isHighlighted - Whether or not the suggestion is highlighted.

It should return a string or aReactElement. For example:

functionrenderSuggestion(suggestion){return<span>{suggestion.text}</span>;}

Important:renderSuggestion must be a pure function (we optimize rendering performance based on this assumption).

Autosuggest is acontrolled component. Therefore, you MUST pass at least avalue and anonChange callback to the input. You can pass any other props as well. For example:

constinputProps={  value,// usually comes from the application state  onChange,// called every time the input value changes  onBlur,// called when the input loses focus, e.g. when user presses Tabtype:"search",placeholder:"Enter city or postcode"};

The signature is:

functiononChange(event,{ newValue, method})

where:

• newValue - the new value of the input
• method - string describing how the change has occurred. The possible values are:
  • 'down' - user pressedDown
  • 'up' - user pressedUp
  • 'escape' - user pressedEscape
  • 'enter' - user pressedEnter
  • 'click' - user clicked (or tapped) on suggestion
  • 'type' - none of the methods above (usually means that user typed something, but can also be that they pressed Backspace, pasted something into the input, etc.)

The signature is:

functiononBlur(event,{ highlightedSuggestion})

where:

• highlightedSuggestion - the suggestion that was highlighted just before the input lost focus, ornull if there was no highlighted suggestion.

Provides arbitrary properties to the outerdiv container of Autosuggest. Allows the override of accessibility properties.

constcontainerProps={dataId:'my-data-id'// ... any other properties};

This function is called when suggestion is selected. It has the following signature:

functiononSuggestionSelected(event,{ suggestion, suggestionValue, suggestionIndex, sectionIndex, method})

where:

• suggestion - the selected suggestion
• suggestionValue - the value of the selected suggestion (equivalent togetSuggestionValue(suggestion))
• suggestionIndex - the index of the selected suggestion in thesuggestions array
• sectionIndex - when renderingmultiple sections, this will be the section index (insuggestions) of the selected suggestion. Otherwise, it will benull.
• method - string describing how user selected the suggestion. The possible values are:
  • 'click' - user clicked (or tapped) on the suggestion
  • 'enter' - user selected the suggestion usingEnter

This function is called when the highlighted suggestion changes. It has the following signature:

functiononSuggestionHighlighted({ suggestion})

where:

• suggestion - the highlighted suggestion, ornull if there is no highlighted suggestion.

By default, suggestions are rendered when the input isn't blank. Feel free to override this behaviour.

This function gets the current value of the input and the reason why the suggestions might be rendered, and it should return a boolean.

For example, to display suggestions only when input value is at least 3 characters long, do:

functionshouldRenderSuggestions(value,reason){returnvalue.trim().length>2;}

You can use the secondreason argument to finely control exactly when the suggestions are rendered. The possible values are closely related to those foronSuggestionsFetchRequested, plus a few extra cases:

• 'input-changed' - user typed something
• 'input-focused' - input was focused
• 'input-blurred' - input was un-focused
• 'escape-pressed' - user pressedEscape to clear the input (and suggestions are shown for empty input)
• 'suggestions-revealed' - user pressedUp orDown to reveal suggestions
• 'suggestions-updated' - the suggestions were updated
• 'render' - the component is re-rendering

WhenshouldRenderSuggestions returnstrue,suggestions will be rendered only when the input is focused.

If you would like to render suggestions regardless of whether the input is focused or not, setalwaysRenderSuggestions={true} (shouldRenderSuggestions is ignored in this case).

SetalwaysRenderSuggestions={true} if you'd like to always render the suggestions.

Important: Make sure that the initial value ofsuggestions corresponds to the initial value ofinputProps.value. For example, if you'd like to show all the suggestions when the input is empty, your initial state should be something like:

this.state={value:"",suggestions:allSuggestions};

WhenhighlightFirstSuggestion={true}, Autosuggest will automatically highlight the first suggestion. Defaults tofalse.

By default,focusInputOnSuggestionClick={true}, which means that, every time suggestion is clicked (or tapped), the input keeps the focus.

On mobile devices, when the input is focused, the native keyboard appears. You'll probably want to lose the focus when suggestion is tapped in order to hide the keyboard.

You can do something like this:

<AutosuggestfocusInputOnSuggestionClick={!isMobile} ... />

whereisMobile is a boolean describing whether Autosuggest operates on a mobile device or not. You can usekaimallea/isMobile, for example, to determine that.

By default, Autosuggest renders a plain list of suggestions.

If you'd like to have multiple sections (with optional titles), setmultiSection={true}.

When renderingmultiple sections, you need to tell Autosuggest how to render a section title.

This function gets the section to render (an item in thesuggestions array), and it should return a string or aReactElement. For example:

functionrenderSectionTitle(section){return<strong>{section.title}</strong>;}

IfrenderSectionTitle returnsnull orundefined, section title is not rendered.

When renderingmultiple sections, you need to tell Autosuggest where to find the suggestions for a given section.

This function gets the section to render (an item in thesuggestions array), and it should return an array of suggestions to render in the given section. For example:

functiongetSectionSuggestions(section){returnsection.suggestions;}

Note: Sections with no suggestions are not rendered.

You shouldn't specifyrenderInputComponent unless you want to customize the rendering of the input.

To keep Autosuggestaccessible,renderInputComponent MUST:

• render an input
• pass through all the providedinputProps to the input

Example:

constrenderInputComponent=inputProps=>(<div><input{...inputProps}/><div>custom stuff</div></div>);

Note: When usingrenderInputComponent, you still need to specify the usualinputProps. Autosuggest will merge theinputProps that you provide with other props that are needed for accessibility (e.g.'aria-activedescendant'), and will pass themergedinputProps torenderInputComponent.

You shouldn't specifyrenderSuggestionsContainer unless you want to customize the content or behaviour of the suggestions container beyond rendering the suggestions themselves. For example, you might want to add a custom text before/after the suggestions list, or tocustomize the scrolling behaviour of the suggestions container.

The signature is:

functionrenderSuggestionsContainer({ containerProps, children, query})

where:

• containerProps - props that you MUST pass to the topmost element that is returned fromrenderSuggestionsContainer.
• children - the suggestions themselves. It's up to you where to render them.
• query - Same asquery inrenderSuggestion.

For example:

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

WhenrenderSuggestionsContainer returns a composite component (e.g.<IsolatedScroll ... /> as opposed to a DOM node like<div ... />), you MUST callcontainerProps.ref with the topmost element that the composite component renders.

For example:

importIsolatedScrollfrom"react-isolated-scroll";functionrenderSuggestionsContainer({ containerProps, children}){const{ ref, ...restContainerProps}=containerProps;constcallRef=isolatedScroll=>{if(isolatedScroll!==null){ref(isolatedScroll.component);}};return(<IsolatedScrollref={callRef}{...restContainerProps}>{children}</IsolatedScroll>);}

Autosuggest comes with no styles.

It usesreact-themeable that allows you to style your Autosuggest component usingCSS Modules,Radium,Aphrodite,JSS,Inline styles, and global CSS.

For example, to style the Autosuggest using CSS Modules, do:

/* theme.css */.container { ... }.input { ... }.suggestionsContainer { ... }.suggestion { ... }.suggestionHighlighted { ... }...

importthemefrom"theme.css";

<Autosuggesttheme={theme} ... />

When not specified,theme defaults to:

{container:'react-autosuggest__container',containerOpen:'react-autosuggest__container--open',input:'react-autosuggest__input',inputOpen:'react-autosuggest__input--open',inputFocused:'react-autosuggest__input--focused',suggestionsContainer:'react-autosuggest__suggestions-container',suggestionsContainerOpen:'react-autosuggest__suggestions-container--open',suggestionsList:'react-autosuggest__suggestions-list',suggestion:'react-autosuggest__suggestion',suggestionFirst:'react-autosuggest__suggestion--first',suggestionHighlighted:'react-autosuggest__suggestion--highlighted',sectionContainer:'react-autosuggest__section-container',sectionContainerFirst:'react-autosuggest__section-container--first',sectionTitle:'react-autosuggest__section-title'}

The following picture illustrates howtheme keys correspond to Autosuggest DOM structure:

The only reasonid exists, is to set ARIA attributes (they require a unique id).

When rendering a single Autosuggest, don't set theid (it will be set to'1', by default).

When rendering multiple Autosuggest components on a page, make sure to give them uniqueids. For example:

<Autosuggestid="source" ... /><Autosuggestid="destination" ... />

npm installnpm start

Now, openhttp://localhost:3000/demo/dist/index.html and start hacking!

MIT