Primitives to build simple, flexible, WAI-ARIA compliant React autocomplete components
You need an autocomplete experience in your application and you want it to be accessible. You also want it to be simple and flexible to account for your use cases.
This is a collection of primitive components that you can compose together to create an autocomplete component which you can reuse in your application. It's based on ideas from the talk "Compound Components" which effectively gives you maximum flexibility with a minimal API because you are responsible for the rendering of the autocomplete components.
This differs from other solutions which render things for their use case and then expose many options to allow for extensibility causing an API that is less easy to use and less flexible as well as making the implementation more complicated and harder to contribute to.
This component is currently under development and is not yet released...
npm install --save react-autocompletely
This package also depends on
prop-types. Please make sure you have those installed as well.
Things are still in flux a little bit (looking for feedback).
import Autocomplete from 'react-autocompletely' // use components together here.
Available components and relevant props:
This is the main component. It renders a
div and forwards props. Wrap everything in this.
function(item: any)| required
Called when the user selects an item
This is the input component. It renders an
input and forwards props.
null| defaults to null
The initial value the input should have when it's mounted.
function(item: any)| defaults to an identity function (
i => String(i))
Used to determine the
inputValue for the selected item.
This component allows you to receive and interact with the state of the autocomplete component.
This is called with an object with the properties listed below:
||the currently highlighted item|
||call to set a new highlighted index|
||the current value of the input|
||the menu open state|
||toggle the menu open state (if
||opens the menu|
||closes the menu|
||the currently selected item|
||clears the selection|
||selects the given item|
||selects the item at the given index|
||selects the item that is currently highlighted|
This component allows you to render the items based on the user input. It renders a
div with another
div for your items and a
div for the menu status (for accessibility purposes)
null| defaults to
This is the initial index to highlight when the menu first opens.
This is called with the same things that the
children prop is called with for
Render your items inside this component. This renders a
div and forwards all props.
this is how
react-autocompletely keeps track of your item when updating the
highlightedIndex as the user keys around.
This is the item data that will be selected when the user selects a particular item.
Examples exist on codesandbox.io:
If you would like to add an example, follow these steps:
- Fork this codesandbox
- Update the code for your example (add some form of documentation to explain what it is)
- Update the title and description
- Add the tag:
You can watch me build the first iteration of
react-autocompletely on YouTube:
You can implement these other solutions using
react-autocompletely, but if you'd prefer to use these out of the box solutions, then that's fine too:
Thanks goes to these people (emoji key):
Kent C. Dodds
This project follows the all-contributors specification. Contributions of any kind welcome!