react-bootstrap-typeahead

The library exposes several components and higher-order components (HOCs) through its top-level module. Use these public interfaces for building typeahead functionality. Any components not listed below should be considered private and subject to change.

Components:

• <Typeahead>
• <AsyncTypeahead>
• <Highlighter>
• <Hint>
• <Input>
• <Menu>
• <MenuItem>
• <TypeaheadInputSingle> & <TypeaheadInputMulti>
• <TypeaheadMenu>
• <Token>

Higher-Order Components & Hooks:

• useAsync & withAsync
• useItem & withItem
• useToken & withToken
• useHint

The react-bootstrap-typeahead component accepts an array of either strings or objects as the options prop.

• Strings: Use a simple Array<String> if you only need to display and select text values.
• Objects: Use an Array<Object> if your data contains metadata. If using objects, each object must contain a string property to serve as the display label.

Important: The component will throw an error if any item in the array is not a string or an object with a valid labelKey.

// Array of strings
var options = ['John', 'Miles'];

// Array of objects (using default 'label' key)
var options = [{id: 1, label: 'John'}, {id: 2, label: 'Miles'}];

You can manage the component's state in two ways:

Controlled (Recommended)

Use the selected prop to drive the component's state from a parent component. This is the recommended approach for managing form state.

Uncontrolled

Use the defaultSelected prop to provide initial values. After the initial render, the component manages its own internal state.

Note: You can control the selections (the items chosen), but you cannot control the raw input text value via these props.

// Controlled Example
<Typeahead
  onChange={(selected) => {
    this.setState({selected});
  }}
  options={[...]}
  selected={this.state.selected}
/>

// Uncontrolled Example
<Typeahead
  defaultSelected={[...]}
  onChange={(selected) => {
    // Handle selections...
  }}
  options={[...]}
/>

The Typeahead component functions like a standard form element. To use it, provide an options prop containing an array of strings or objects. Use the onChange callback to handle the user's selections.

<Typeahead
  onChange={(selected) => {
    // Handle selections...
  }}
  options={[ /* Array of objects or strings */ ]}
/>

In version 3.0, the filterBy callback signature changed. The second parameter is no longer the user-input text string; it is now an object containing internal props. To access the text value, use props.text.

// v2.0
<Typeahead
  ...
  filterBy={(option, text) => {
    // Your own filtering code goes here.
  }}
/>

// v3.0
<Typeahead
  ...
  filterBy={(option, props) => {
    // Your own filtering code goes here.
    // `text` is now `props.text`
  }}
/>

Version 3.0 uses Popper.js for menu positioning. If you use a custom component for the renderMenu prop, your component must consume the innerRef prop passed down by Popper and attach it to your component's ref to ensure correct positioning.

class MyCustomMenu extends React.Component {
  render() {
    // `innerRef` is passed down by the Popper...
    const {innerRef, ...props} = this.props;

    // ...and must be passed to the `ref` of your custom component.
    return <div {...props} ref={innerRef} />;
  }
}

You can install the package using npm or yarn. This package provides a React-based typeahead component that relies on Bootstrap for styling and supports both single- and multi-selection while being WAI-ARIA compliant.

npm install --save react-bootstrap-typeahead
# or
yarn add react-bootstrap-typeahead

Import as a module in your JS

import 'react-bootstrap-typeahead/css/Typeahead.css';
// For Bootstrap 5, also include:
import 'react-bootstrap-typeahead/css/Typeahead.bs5.css';

Link as a stylesheet in your HTML

<link
  rel="stylesheet"
  href="https://unpkg.com/react-bootstrap-typeahead/css/Typeahead.css"
/>
<!-- For Bootstrap 5, also include:
<link
  rel="stylesheet"
  href="https://unpkg.com/react-bootstrap-typeahead/css/Typeahead.bs5.css"
/> -->