WAI-ARIA compliant React autosuggest component
npm install react-autosuggest-legacy[WAI-ARIA compliant][wai-aria] React autosuggest legacy component.
Compatible with 2.x API with support for React 15 and updated dependencies
* [WAI-ARIA accessible][wai-aria] (including ARIA attributes and keyboard interactions)
* Mobile friendly
* Supports controlled and uncontrolled state
* Supports react-themeable for flexible styling
* Supports [multiple sections][multiple-sections] as well as [plain list of suggestions][basic-example]
* Supports delayed requests (if request comes back after user types another letter, it will be ignored)
* Full control over suggestion rendering (you can display extra data, images, whatever you want)
* Full control over when to show the suggestions (e.g. when user types 2 or more characters)
* Various hooks: onSuggestionSelected, onSuggestionFocused, onSuggestionUnfocused
* Ability to pass props to the input field (e.g. initial value, placeholder, type, onChange, onBlur)
* In-memory caching (suggestions for a given input are retrieved only once). Can be disabled.
* Thoroughly tested (over 120 tests)
``shell`
npm install react-autosuggest-legacy --save
#### CommonJS module:
`js
import Autosuggest from 'react-autosuggest-legacy';
const suburbs = ['Cheltenham', 'Mill Park', 'Mordialloc', 'Nunawading'];
function getSuggestions(input, callback) {
const regex = new RegExp('^' + input, 'i');
const suggestions = suburbs.filter(suburb => regex.test(suburb));
setTimeout(() => callback(null, suggestions), 300); // Emulate API call
}
`xml`
* suggestions
* suggestionRenderer
* suggestionValue
* defaultValue
* value
* showWhen
* onSuggestionSelected
* onSuggestionFocused
* onSuggestionUnfocused
* inputAttributes
* cache
* id
* scrollBar
* theme
Implement this function to tell Autosuggest which suggestions to display.
`js`
function(input, callback) {
...
}
* input - Will be the value of the input fieldcallback
* - Should be called once the suggestions are in hand, or error occurs.
* Success example: callback(null, \)
* Error example:
can have one of the following two formats:
* To display a single section with no title: [\, \, ...]
* To display one or more sections with optional titles: Array of objects with an optional and a mandatory suggestions keys, e.g.:
`js`
[{
suggestions: [
}, {
sectionName: 'Second section',
suggestions: [
}]
can have one of the following two formats:
* String, e.g.: 'Mentone'
* Object, e.g.: . 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.
`js`
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:
`js`
function renderSuggestion(suggestion, input) { // In this example, 'suggestion' is a string
return ( // and it returns a ReactElement
{suggestion.slice(0, input.length)}{suggestion.slice(input.length)}
);
}
`xml`
#### 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:
`js`
function getSuggestionValue(suggestionObj) {
return suggestionObj.suburb + ' VIC ' + suggestionObj.postcode;
}
`xml`
suggestionValue={getSuggestionValue} />
You may use defaultValue only if you want Autosuggest to behave in an uncontrolled manner (the component keeps track of its state internally). In this case you cannot use value.
defaultValue is simply the initial value of the input.
For example:
`xml`
... />
When specified, Autosuggest behaves in a controlled manner (the component uses an outside source of state).
value is simply the value of the input.
For example:
`xml`
... />
When value is not specified, Autosuggest behaves in an uncontrolled manner (the component keeps track of its state internally).
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:
`js`
function(input) {
return input.trim().length > 0;
}
For example, this is how you could show suggestions only when user typed 2 or more characters:
`xml`
#### onSuggestionSelected (optional)
This function will be called when suggestion is selected via mouse click or Enter.
`js`
function(suggestion, event) {
...
}
* suggestion - The selected suggestion
* [event][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:
`js`
function onSuggestionSelected(suggestion, event) {
event.preventDefault();
// Do other fancy stuff
}
`xml`
#### onSuggestionFocused (optional)
This function will be called when suggestion is focused via mouse hover or Up/Down keys.
`js`
function(suggestion) {
...
}
* suggestion - The focused suggestion
For example:
`js`
function onSuggestionFocused(suggestion) { // In this example 'suggestion' is a string
console.log('Suggestion focused: [' + suggestion + ']');
}
`xml`
#### onSuggestionUnfocused (optional)
This function will be called when suggestion is unfocused.
`js`
function(suggestion) {
...
}
* suggestion - The unfocused suggestion
For example:
`js`
function onSuggestionUnfocused(suggestion) { // In this example 'suggestion' is a string
console.log('Suggestion unfocused: [' + suggestion + ']');
}
`xml`
#### inputAttributes (optional)
Hash of attributes to pass to the input field. For example:
`jsInput value changed to: ${value}
const inputAttributes = {
id: 'locations-autosuggest',
name: 'locations-autosuggest',
className: 'my-sweet-locations-autosuggest',
placeholder: 'Enter locations...',
type: 'search',
onChange: value => console.log(),`
onBlur: event => console.log('Input blurred. Event:', event)
};
`xml`
Defaults to true, meaning that the suggestions function will be called only once for a given input.
For example, if user types m, and suggestions are retrieved, we store the result in memory. Then, if user types e and hits Backspace, we get the suggestions for m from the cache.
Set cache={false} to disable this behaviour.
#### id (required when multiple Autosuggests are rendered on a page)
The only reason id exists, is to set ARIA attributes (they require a unique id).
When rendering a single Autosuggest, don't set the id (it will be set to '1', by default).
When rendering multiple Autosuggests, make sure to give them unique ids. For example:
`xml`
Set it to true only if suggestions container (react-autosuggest__suggestions) can have a scroll bar (e.g. if it has height: 200px; overflow: auto). Suggestions container must be a positioned element in this case. When set to true, suggestions container will adjust its scroll bar every time user interacts using the Up and Down keys (see the this example).
Defaults to false.
Autosuggest comes with no styles, and it supports react-themeable.
This means you can use CSS Modules, Radium, React Style, JSS, inline styles, or even global CSS to style your Autosugest component.
For example, to style the Autosuggest using CSS Modules, do:
`css
/ theme.css /
.root { ... }
.suggestions { ... }
.suggestion { ... }
.suggestionIsFocused { ... }
.section { ... }
.sectionName { ... }
.sectionSuggestions { ... }
`
`js`
import theme from 'theme.css';xml`
When not specified, theme defaults to:
`js`
{
root: 'react-autosuggest',
suggestions: 'react-autosuggest__suggestions',
suggestion: 'react-autosuggest__suggestion',
suggestionIsFocused: 'react-autosuggest__suggestion--focused',
section: 'react-autosuggest__suggestions-section',
sectionName: 'react-autosuggest__suggestions-section-name',
sectionSuggestions: 'react-autosuggest__suggestions-section-suggestions'
}
An example of styling the Autosuggest using these global classes can be found in examples/src/Autosuggest.less
The following diagrams explain the classes above.
##### No sections
+---| react-autosuggest |-------------------------+
| |
| |
| |
| +--| react-autosuggest__suggestions |-------+ |
| | | |
| | +--| react-autosuggest__suggestion |--+ | |
| | | | | |
| | +-------------------------------------+ | |
| | | |
| +-------------------------------------------+ |
| |
+-------------------------------------------------+
##### Multiple sections
+---| react-autosuggest |----------------------------------------------------+
| |
| |
| |
| +--| react-autosuggest__suggestions |----------------------------------+ |
| | | |
| | +--| react-autosuggest__suggestions-section |--------------------+ | |
| | | | | |
| | | +--| react-autosuggest__suggestions-section-name |---------+ | | |
| | | | | | | |
| | | +----------------------------------------------------------+ | | |
| | | | | |
| | | +--| react-autosuggest__suggestions-section-suggestions |--+ | | |
| | | | | | | |
| | | | +--| react-autosuggest__suggestion |-----------------+ | | | |
| | | | | | | | | |
| | | | +----------------------------------------------------+ | | | |
| | | | | | | |
| | | +----------------------------------------------------------+ | | |
| | | | | |
| | +----------------------------------------------------------------+ | |
| | | |
| +----------------------------------------------------------------------+ |
| |
+----------------------------------------------------------------------------+
`shell`
npm start
Now, open http://localhost:3000/examples/dist/index.html and start hacking!
`shell``
npm test
MIT
[wai-aria]: https://www.w3.org/TR/wai-aria-practices/#autocomplete
[event]: https://facebook.github.io/react/docs/events.html#syntheticevent
[basic-example]: https://moroshko.github.io/react-autosuggest
[multiple-sections]: https://moroshko.github.io/react-autosuggest/#Multiple%20sections