Are you happy with your logging solution? Would you help us out by taking a 30-second survey? Click here

react-autocomplete

WAI-ARIA compliant React autocomplete (combobox) component

Star full 4f7b624809470f25b6493d5a7b30d9b9cb905931146e785d67c86ef0c205a402Star full 4f7b624809470f25b6493d5a7b30d9b9cb905931146e785d67c86ef0c205a402Star full 4f7b624809470f25b6493d5a7b30d9b9cb905931146e785d67c86ef0c205a402Star full 4f7b624809470f25b6493d5a7b30d9b9cb905931146e785d67c86ef0c205a402Star blank 374f33e4d622a2930833db3cbea26b5d03dc44961a6ecab0b9e13276d97d6682 (1 ratings)
Rated 4.0 out of 5
Subscribe to updates I use react-autocomplete


Statistics on react-autocomplete

Number of watchers on Github 1578
Number of open issues 34
Average time to close an issue 23 days
Main language JavaScript
Average time to merge a PR 13 days
Open pull requests 78+
Closed pull requests 35+
Last commit almost 2 years ago
Repo Created over 5 years ago
Repo Last Updated over 1 year ago
Size 3.57 MB
Organization / Authorreactjs
Contributors5
Page Updated
Do you use react-autocomplete? Leave a review!
View open issues (34)
View react-autocomplete activity
View on github
Fresh, new opensource launches 🚀🚀🚀
Trendy new open source projects in your inbox! View examples

Subscribe to our mailing list

Evaluating react-autocomplete for your project? Score Explanation
Commits Score (?)
Issues & PR Score (?)

React Autocomplete Travis build status

Accessible, extensible, Autocomplete for React.js.

<Autocomplete
  getItemValue={(item) => item.label}
  items={[
    { label: 'apple' },
    { label: 'banana' },
    { label: 'pear' }
  ]}
  renderItem={(item, isHighlighted) =>
    <div style={{ background: isHighlighted ? 'lightgray' : 'white' }}>
      {item.label}
    </div>
  }
  value={value}
  onChange={(e) => value = e.target.value}
  onSelect={(val) => value = val}
/>

Check out more examples and get stuck right in with the online editor.

Install

npm

npm install --save react-autocomplete

yarn

yarn add react-autocomplete

AMD/UMD

API

Props

getItemValue: Function

Arguments: item: Any

Used to read the display value from each entry in items.

items: Array

The items to display in the dropdown menu

renderItem: Function

Arguments: item: Any, isHighlighted: Boolean, styles: Object

Invoked for each entry in items that also passes shouldItemRender to generate the render tree for each item in the dropdown menu. styles is an optional set of styles that can be applied to improve the look/feel of the items in the dropdown menu.

autoHighlight: Boolean (optional)

Default value: true

Whether or not to automatically highlight the top match in the dropdown menu.

inputProps: Object (optional)

Default value: {}

Props passed to props.renderInput. By default these props will be applied to the <input /> element rendered by Autocomplete, unless you have specified a custom value for props.renderInput. Any properties supported by HTMLInputElement can be specified, apart from the following which are set by Autocomplete: value, autoComplete, role, aria-autocomplete. inputProps is commonly used for (but not limited to) placeholder, event handlers (onFocus, onBlur, etc.), autoFocus, etc..

isItemSelectable: Function (optional)

Default value: function() { return true }

Arguments: item: Any

Invoked when attempting to select an item. The return value is used to determine whether the item should be selectable or not. By default all items are selectable.

menuStyle: Object (optional)

Default value:

{
  borderRadius: '3px',
  boxShadow: '0 2px 12px rgba(0, 0, 0, 0.1)',
  background: 'rgba(255, 255, 255, 0.9)',
  padding: '2px 0',
  fontSize: '90%',
  position: 'fixed',
  overflow: 'auto',
  maxHeight: '50%', // TODO: don't cheat, let it flow to the bottom
}

Styles that are applied to the dropdown menu in the default renderMenu implementation. If you override renderMenu and you want to use menuStyle you must manually apply them (this.props.menuStyle).

onChange: Function (optional)

Default value: function() {}

Arguments: event: Event, value: String

Invoked every time the user changes the input's value.

onMenuVisibilityChange: Function (optional)

Default value: function() {}

Arguments: isOpen: Boolean

Invoked every time the dropdown menu's visibility changes (i.e. every time it is displayed/hidden).

onSelect: Function (optional)

Default value: function() {}

Arguments: value: String, item: Any

Invoked when the user selects an item from the dropdown menu.

open: Boolean (optional)

Used to override the internal logic which displays/hides the dropdown menu. This is useful if you want to force a certain state based on your UX/business logic. Use it together with onMenuVisibilityChange for fine-grained control over the dropdown menu dynamics.

renderInput: Function (optional)

Default value:

function(props) {
  return <input {...props} />
}

Arguments: props: Object

Invoked to generate the input element. The props argument is the result of merging props.inputProps with a selection of props that are required both for functionality and accessibility. At the very least you need to apply props.ref and all props.on<event> event handlers. Failing to do this will cause Autocomplete to behave unexpectedly.

renderMenu: Function (optional)

Default value:

function(items, value, style) {
  return <div style={{ ...style, ...this.menuStyle }} children={items}/>
}

Arguments: items: Array<Any>, value: String, styles: Object

Invoked to generate the render tree for the dropdown menu. Ensure the returned tree includes every entry in items or else the highlight order and keyboard navigation logic will break. styles will contain { top, left, minWidth } which are the coordinates of the top-left corner and the width of the dropdown menu.

selectOnBlur: Boolean (optional)

Default value: false

Whether or not to automatically select the highlighted item when the <input> loses focus.

shouldItemRender: Function (optional)

Arguments: item: Any, value: String

Invoked for each entry in items and its return value is used to determine whether or not it should be displayed in the dropdown menu. By default all items are always rendered.

sortItems: Function (optional)

Arguments: itemA: Any, itemB: Any, value: String

The function which is used to sort items before display.

value: Any (optional)

Default value: ''

The value to display in the input field

wrapperProps: Object (optional)

Default value: {}

Props that are applied to the element which wraps the <input /> and dropdown menu elements rendered by Autocomplete.

wrapperStyle: Object (optional)

Default value:

{
  display: 'inline-block'
}

This is a shorthand for wrapperProps={{ style: <your styles> }}. Note that wrapperStyle is applied before wrapperProps, so the latter will win if it contains a style entry.

Imperative API

In addition to the props there is an API available on the mounted element which is similar to that of HTMLInputElement. In other words: you can access most of the common <input> methods directly on an Autocomplete instance. An example:

class MyComponent extends Component {
  componentDidMount() {
    // Focus the input and select "world"
    this.input.focus()
    this.input.setSelectionRange(6, 11)
  }
  render() {
    return (
      <Autocomplete
        ref={el => this.input = el}
        value="hello world"
        ...
      />
    )
  }
}

Development

You can start a local development environment with npm start. This command starts a static file server on localhost:8080 which serves the examples in examples/. Hot-reload mechanisms are in place which means you don't have to refresh the page or restart the build for changes to take effect.

Tests!

Run them: npm test

Write them: lib/__tests__/Autocomplete-test.js

Check your work: npm run coverage

Scripts

Run with npm run <script>.

gh-pages

Builds the examples and assembles a commit which is pushed to origin/gh-pages, then cleans up your working directory. Note: This script will git checkout master before building.

release

Takes the same argument as npm publish, i.e. [major|minor|patch|x.x.x], then tags a new version, publishes, and pushes the version commit and tag to origin/master. Usage: npm run release -- [major|minor|patch|x.x.x]. Remember to update the CHANGELOG before releasing!

build

Runs the build scripts detailed below.

build:component

Transpiles the source in lib/ and outputs it to build/, as well as creating a UMD bundle in dist/.

build:examples

Creates bundles for each of the examples, which is used for pushing to origin/gh-pages.

test

Runs the test scripts detailed below.

test:lint

Runs eslint on the source.

test:jest

Runs the unit tests with jest.

coverage

Runs the unit tests and creates a code coverage report.

start

Builds all the examples and starts a static file server on localhost:8080. Any changes made to lib/Autocomplete.js and the examples are automatically compiled and transmitted to the browser, i.e. there's no need to refresh the page or restart the build during development. This script is the perfect companion when making changes to this repo, since you can use the examples as a test-bed for development.

react-autocomplete open issues Ask a question     (View All Issues)
  • about 3 years Current build of dist/react-autocomplete.js does not seem to be honoring inputProps.onKeyUp
  • about 3 years Uncaught TypeError: Cannot read property 'ownerDocument' of null
  • about 3 years Getting Uncaught ReferenceError: global is not defined(…)
  • about 3 years Use TextField from material-ui
  • about 3 years How to let the position of the list items be relative?
  • about 3 years Update Readme?
  • about 3 years Add aria-activedescendant
  • about 3 years Unknown option: .babelrc.presets
  • about 3 years Examples are missing
  • over 3 years Replace rackt-cli
  • over 3 years Documentation for 1.x outline
  • over 3 years Remove eslint rule overrides
  • over 3 years Poor render performance on lists of >500 items
  • over 3 years Public API: The Basics
  • over 3 years Should dist and build folders store in repo?
  • over 3 years Immutablejs support
  • over 4 years New API proposal
  • over 4 years Required ARIA children role not present: listbox textbox
  • over 4 years Control opening direction up/down
  • over 4 years Trigger event with query when Enter key is pressed
  • over 5 years Add copyright comment?
  • over 5 years typing with async options gets funky
react-autocomplete open pull requests (View All Pulls)
  • [fixed] handleChange should use event.persist()
  • Use 'absolute' positioning for menu instead of 'fixed'
  • Call setMenuPositions() on scroll & resize
  • [fixed] Prevent autocomplete when clicking a non-focusable input
  • [added] select item on arrow right key down
  • Stop keeping value in state
  • ArrowDown() needs event argument
  • Fire onSelect event even if there is no match items
  • add linting using eslint consuming the rackt config
  • Allows onBlur function to be set as additional component prop
  • [fixed] Add missing event argument to ArrowDown handler
  • [fixed]: check item length before calling scrollinto view
  • [added] wrapperProps and wrapperStyle props
  • Make getItemValue required
  • typos in main.js
  • Typo corrections in handleInput code comments
  • remove jsx pragma (React 0.13 compat)
  • Added browserify directive to make sure that JSX->JS transform happens w...
  • only focus ComboboxOption elements
  • [added] new props: onFocus and onBlur
  • [added]add limitation of menu result item amount
  • [changed]Set the position of menu as "absolute" instead of "fixed"
  • Issue41
  • Include an 'id' prop
  • Dependency cleanup
  • [changed] Disable native autocomplete
  • [changed] Prevent `Return` in menu from submitting surrounding form
  • [removed] Remove lodash dependency and hardcoded label
  • [added] passed through event to onSelect prop callback
  • [fixed] Select highlighted item on input click
  • Correctly filter items when selecting a state, fixes #81
  • Support mobile safari's broken offsets
  • Support React v15
  • new build in order for wrapperStyles and wrapperProps to work as expected
  • fix arrow up/down bug when list is empty
  • Enable adding label properties
  • renderMenu prop
  • Add getItemValue to propTypes
  • Add default z-index to menu style
  • [fixed] Fix input click test
  • [fixed] Update homepage, repo, and bug URLs in README
  • [changed] Add prop for disabling text selection range.
  • added onBlur and onFocus props
  • Fix usage findDOMnode(deprecated)
  • Tweaks
  • Replace mocha/chai/isparta with jest
  • Fix: state.value to props.value
  • Fixed "Uncaught TypeError: React.findDOMNode is not a function"
  • added onBlur and onFocus props
  • [fixed] Prevent event handler clobbering (fixes #123)
  • Listing of Props in README to being basis of documentation
  • [changed] set the position of the menu as fixed
  • Deprecate string ref
  • Add key to rendered item
  • Nicer sorting algorithm for example
  • Add build instructions to readme
  • [added] Allow Tab to select option
  • Update package.json main to point to actual main file
  • Update example URL
  • Replace rackt-cli with custom build
  • Deprecate string ref
  • fix #176 - ownerDocument error ..for now
  • [fixed] Upgraded React.createClass(...) to ES6 classes
  • Removes the usage of createClass and retrieving prop types from the main React package
  • Ignore blur while hovering over menu
  • Allow setting HTML autocomplete attribute
  • Set ignore blur based on mouse position.
  • Do not highlight when the event's keyCode is NOT `13`
  • [added] Add isItemSelectable prop function (#237)
  • Fixed #307: ignore blur on touch start.
  • Added setIgnoreBlur(false) to Enter-event
  • New default behavior onMouseOut
  • [added] optional custom function to compare input value to list option values
  • fix #287 - checks itemNode is not null in maybeScrollItemIntoView
  • [changed] isOpen function treats null or undefined prop as not being set
  • babel-preset-es2015 -> babel-preset-env
  • Fixing crash when itemNode is not found
  • WIP: use span instead of div for wrapper-element
react-autocomplete questions on Stackoverflow (View All Questions)
  • React autocomplete component within a modal
react-autocomplete list of languages used
Other projects in JavaScript