React Bootstrap Typeahead
React-based typeahead component that uses Bootstrap as a base for styles and behaviors and supports both single- and multi-selection. The UI and behaviors are inspired by Twitter's typeahead.js. Try a live example.
Please note that this library is under active development and the APIs may change. The documentation below applies to the most recent version and may no longer be applicable if you're using an outdated version.
Use NPM to install the module in your project:
npm install --save react-bootstrap-typeahead
Minified and unminified UMD modules are also included in the NPM package, or you can clone the project and
npm run build to generate these files.
Importing vs. Requiring
The component is written using ES6 modules and transpiled with Babel 6. If you are also using ES6, you can simply
import just as you would any other module:
import Typeahead from 'react-bootstrap-typeahead';
If you're using CommonJS, you'll need to explicitly specify
var Typeahead = default;
Alternatively, you can use the
add-module-exports Babel plugin to avoid having to add
The component behaves similar to other form elements. It requires an array of options to be displayed, similar to a
Single & Multi-Selection
The component provides single-selection by default, but also supports multi-selection. Simply set the
multiple prop and the component turns into a tokenizer:
Controlled vs. Uncontrolled
input, the component can be controlled or uncontrolled. Use the
selected prop to control it via the parent, or
defaultSelected to optionally set defaults and then allow the component to control itself.
react-bootstrap-typeahead accepts an array of either strings or objects. If you pass in objects, each one should have a string property to be used as the label for display. By default, the key is named
label, but you can specify a different key via the
labelKey prop. If you pass an array of strings, the
labelKey prop will be ignored.
The component will throw an error if any options are something other than a string or object with a valid
The following are valid data structures:
// Array of strings.var myData ='John''Miles''Charles''Herbie';// Array of objects with default `labelKey`.var myData =id: 1 label: 'John'id: 2 label: 'Miles'id: 3 label: 'Charles'id: 4 label: 'Herbie';// Array of objects with custom `labelKey`.// The `labelKey` prop must be set to 'name' in this case.var myData =id: 1 name: 'John'id: 2 name: 'Miles'id: 3 name: 'Charles'id: 4 name: 'Herbie';// Mixed array of strings and objects.// Note: while valid, this is NOT recommended.var myData ='John''Miles'id: 3 label: 'Charles''Herbie';
By default, the component will filter results based on a case-insensitive string match between the input string and the
labelKey property of each option (or the option itself, if an array of strings is passed). You can customize the filtering by passing your own callback to the
You may have unexpected results if your data contains duplicate options. For this reason, it is highly recommended that you pass in objects with unique identifiers (eg: an id) if possible.
The component simply handles rendering and selection of the data that is passed in. It is agnostic about the data source (eg: an async endpoint), which should be handled separately.
react-bootstrap-typeahead is intended to work with standard Bootstrap components and styles. It provides basic rendering for your data by default, but also allows for more advanced options should the need arise.
Allows you to control the contents of a menu item. Your function will be passed the
TypeaheadMenu props, an individual option from your data list, and the index:
Provides the ability to customize rendering of tokens when multiple selections are enabled. The first parameter is the current selected option in the loop, while the second parameter is the
onRemove callback passed down by the main component. This callback is a no-op if
multiple is false.
Be careful when using
renderToken, since you will need to handle things like disabling the tokens and removing them (via
onRemove) yourself. It is highly recommended that you use the provided
// ES2015import Token from 'react-bootstrap-typeahead/lib/Token.react';// CommonJSconst Token = ;
Note that if you use your own component to render the token, you will lose built-in functionality like removing via keystroke.
To access the component's public methods, add a ref to your typeahead instance:
<Typeahead ="typeahead" ... />
then access the ref from your handler:
<button =>Clear Typeahead</button>
Note that you must use
getInstance to get the typeahead instance. This is because
react-bootstrap-typeahead is wrapped by the
react-onclickoutside higher-order component, so the
clear method is not directly available. See
react-onclickoutside's documentation for more information.
Provides a programmatic way to blur the input.
Provides a programmatic way to reset the input. Calling the method will clear both text and selection(s).
Provides a programmatic way to focus the input.
|align||string||'justify'||Specify menu alignment. The default value is
|allowNew||boolean||false||Allows the creation of new selections on the fly. Any new items will be added to the list of selections, but not the list of original options unless handled as such by
||Specify any pre-selected options. Use only if you want the component to be uncontrolled.|
|disabled||boolean||Whether to disable the input. Will also disable selections when
|dropup||boolean||false||Specify whether the menu should appear above the input.|
|emptyLabel||string||'No matches found.'||Message to display in the menu if there are no valid results.|
|filterBy||function||Optional callback to use when filtering the options. The function will receive each option as the first parameter.|
|labelKey||string||'label'||Specify which option key to use for display. By default, the selector will use the
||Maximum height of the dropdown menu, in px.|
||Maximum number of results to display by default. Mostly done for performance reasons so as not to render too many DOM nodes in the case of large data sets.|
||Number of input characters that must be entered before showing results.|
||Whether or not multiple selections are allowed.|
|name||string||Name property for the input|
|newSelectionPrefix||string||'New selection:'||Provides the ability to specify a prefix before the user-entered text to indicate that the selection will be new. No-op unless
|onBlur||function||Callback fired when the input is blurred. Receives an event.|
|onChange||function||Callback fired whenever items are added or removed. Receives an array of the selected options.|
|onFocus||function||Callback fired when the input is focused. Receives an event.|
|onInputChange||function||Callback fired when user-input text changes. Receives the text string.|
||array||Full set of options, including any pre-selected options.|
||Give user the ability to display additional results if the number of results exceeds
|paginationText||string||'Display additional results...'||Prompt displayed when large data sets are paginated.|
|placeholder||string||Placeholder text for the input.|
|renderMenuItemChildren||function||Provides a hook for customized rendering of menu item contents.|
|renderToken||function||Provides a hook for customized rendering of tokens when multiple selections are enabled.|
||The selected option(s) displayed in the input. Use this prop if you want to control the component via its parent.|
The component tries to use as little CSS as possible, relying primarily on Bootstrap or any Bootstrap themes for styling. Some minimal styling is included in
Token.css and should ideally be included wherever you're using the component.
To modify the example, clone the repository,
npm install and
npm run example to build the example index file. You can then open the HTML file locally in a browser. You can also try the live example.
Recent versions of the following browsers are supported:
- IE (10/11)