API Reference

The components and higher-order components (HOCs) described below are publicly exposed in the top-level module. Other components should be considered private and subject to change without notice.

Components

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

Higher-Order Components & Hooks

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

Components

<Typeahead>

The primary component provided by the module.

Props

(results: Array<Object|string>, props: Object) => boolean

(selected: Array<Object|string>) => void

(text: string, event: Event) => void

(event: Event) => void

(isOpen: boolean) => void

(event: Event, shownResults: number) => void

(shouldSelectHint: boolean, KeyboardEvent<HTMLInputElement>) => boolean

Children

In addition to the props listed above, Typeahead also accepts either children or a child render function.

<Typeahead ... >
  <div>Render me!</div>
</Typeahead>

The render function receives partial internal state from the component:

<Typeahead ... >
  {(state) => (
    <div>Render me!</div>
  )}
</Typeahead>

This may be useful for things like customizing the loading indicator or clear button, or including an announcer for accessibility purposes.

<AsyncTypeahead>

An enhanced version of the normal Typeahead component for use when performing asynchronous searches. Provides debouncing of user input, optional query caching, and search prompt, empty results, and pending request behaviors.

<AsyncTypeahead
  isLoading={this.state.isLoading}
  labelKey={option => `${option.login}`}
  onSearch={(query) => {
    this.setState({isLoading: true});
    fetch(`https://api.github.com/search/users?q=${query}`)
      .then(resp => resp.json())
      .then(json => this.setState({
        isLoading: false,
        options: json.items,
      }));
  }}
  options={this.state.options}
/>

Note that this component is the same as:

import { Typeahead, withAsync } from 'react-bootstrap-typeahead';

const AsyncTypeahead = withAsync(Typeahead);

Props

(query: string) => void

<Highlighter>

Component for highlighting substring matches in the menu items.

<Typeahead
  ...
  renderMenuItemChildren={(option, props, idx) => (
    <Highlighter search={props.text}>
      {option[props.labelKey]}
    </Highlighter>
  )}
/>

Props

<Hint>

The Hint component can be used to wrap custom inputs.

<Typeahead
  ...
  renderInput={({ inputRef, referenceElementRef, ...inputProps }) => (
    <Hint>
      <FloatingLabel controlId="name" label="Name">
        <Form.Control
          {...inputProps}
          ref={(node) => {
            inputRef(node);
            referenceElementRef(node);
          }}
          type="text"
        />
      </FloatingLabel>
    </Hint>
  )}
/>

Props

<Input>

Abstract <input> component that handles an inputRef prop and is used as the basis for both single- and multi-select input components.

<Menu>

Provides the markup for a Bootstrap menu, along with some extra functionality for specifying a label when there are no results.

<MenuItem>

Provides the markup for a Bootstrap menu item, but is wrapped by the withItem HOC to ensure proper behavior within the typeahead context. Provided for use if a more customized Menu is desired.

Props

<TypeaheadInputSingle> & <TypeaheadInputMulti>

Input components that handles single- and multi-selections, respectively. In the multi-select component, selections are rendered as children.

Props

<TypeaheadMenu>

The default menu which is rendered by the Typeahead component. Can be used in a custom renderMenu function for wrapping or modifying the props passed to it without having to re-implement the default functionality.

Props

<Token>

Individual token component, most commonly for use within renderToken to customize the Token contents.

Props

Higher-Order Components & Hooks

useAsync & withAsync

The HOC used in AsyncTypeahead.

useItem & withItem

Connects individual menu items with the main typeahead component via context and abstracts a lot of complex functionality required for behaviors like keying through the menu and input hinting. Also provides onClick behavior and active state.

If you use your own menu item components (in renderMenu for example), you are strongly advised to use either the hook or the HOC:

import { MenuItem } from 'react-bootstrap';
import { Menu, Typeahead, useItem, withItem } from 'react-bootstrap-typeahead';

const Item = withItem(MenuItem);

// OR

const Item = (props) => <MenuItem {...useItem(props)} />;

<Typeahead
  renderMenu={(results, menuProps) => (
    <Menu {...menuProps}>
      {results.map((option, position) => (
        <Item option={option} position={position}>
          {option.label}
        </Item>
      ))}
    </Menu>
  )}
/>

useToken & withToken

Encapsulates keystroke and outside click behaviors used in Token. Useful if you want completely custom markup for the token. The hook and the HOC provide the following props to be consumed by the token component:

// Important: use `forwardRef` to pass the ref on to the underlying DOM nodes.
const MyToken = forwardRef(({ active, onRemove, ...props }, ref) => (
  <div
    {...props}
    className={active ? 'active' : ''}
    ref={ref}>
    <button onClick={onRemove}>
      x
    </button>
  </div>
));

// HOC
const CustomToken = withToken(MyToken);

// Hook
const CustomToken = (props) => <MyToken {...useToken(props)} />;

If using the hook, you can also apply it directly within your token component:

const MyToken = (props) => {
  const { active, onRemove, ref, ...otherProps } = useToken(props);

  return (
    <div
      {...otherProps}
      className={active ? 'active' : ''}
      ref={ref}>
      <button onClick={onRemove}>
        x
      </button>
    </div>
  );
};

useHint

Hook for adding a hint to a custom input. Mainly useful if you'd like to customize the hint's markup.

const CustomHint = (props) => {
  const { hintRef, hintText } = useHint(props);

  return (
    <div ... >
      {props.children}
      <input
        ...
        ref={hintRef}
        value={hintText}
      />
    </div>
  );
};

See the Hint component for an example of how to apply useHint.