Skip to content

Latest commit

 

History

History
178 lines (134 loc) · 6.81 KB

API.md

File metadata and controls

178 lines (134 loc) · 6.81 KB

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

Only a subset of props are documented below, primarily those expecting functions. See the props documentation for the full list of options.

<Typeahead>

The primary component provided by the module.

Props

allowNew: boolean|Function

If a boolean is specified, indicates whether new entry functionality should be enabled. When true, a new entry menu item will be included when the trimmed input is not falsey and there isn't an exact match against the input.

If a function is specified, implicity enables new entry functionality, but allows for a user defined callback to decide whether the new entry menu item should be included in the results list. The callback should return a boolean value and the signature is as follows:

allowNew(results: Array<string|Object>, props: Object): bool
filterBy: Array<String>|Function

See full documentation in the Filtering section.

labelKey: String|Function

See full documentation in the Rendering section.

renderMenu: Function, renderMenuItemChildren: Function, and renderToken: Function

See full documentation in the Rendering section.

onChange(selected: Array<Object|String>)

Invoked when the set of selections changes (ie: an item is added or removed). For consistency, selectedItems is always an array of selections, even if multi-selection is not enabled.

onInputChange(text: String, event: Event)

Invoked when the input value changes. Receives the string value of the input (text), as well as the original event.

onBlur(event: Event), onFocus(event: Event), onKeyDown(event: Event)

As with a normal text input, these are called when the typeahead input has blur, focus, or keydown events.

onMenuToggle(isOpen: Boolean)

Invoked when menu visibility changes.

onMenuHide() & onMenuShow()

DEPRECATED Invoked when the menu is hidden or shown, respectively.

onPaginate(event: Event, shownResults: Number)

Invoked when the pagination menu item is clicked. Receives an event as the first argument and the number of shown results as the second.

<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}
  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 {asyncContainer, Typeahead} from 'react-bootstrap-typeahead';

const AsyncTypeahead = asyncContainer(Typeahead);

Props

isLoading: Boolean (required)

Whether or not an asynchronous request is in progress.

onSearch(query: String) (required)

Callback to perform when the search is executed. query is the text string entered by the user.

<Highlighter>

Component for highlighting substring matches in the menu items.

Props

search: String (required)

The substring to look for. This value should correspond to the input text of the typeahead and can be obtained via the onInputChange prop or from the text property of props being passed down via renderMenu or renderMenuItemChildren.

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

<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 with the menuItemContainer HOC to ensure proper behavior within the typeahead context. Provided for use if a more customized Menu is desired.

Props

option: Object (required)

The data item to be displayed.

position: Number

The position of the item as rendered in the menu. Allows the top-level Typeahead component to be be aware of the item's position despite any custom ordering or grouping in renderMenu. Note: The value must be a unique, zero-based, sequential integer for proper behavior when keying through the menu.

<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.

<Token>

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

Higher-Order Components

asyncContainer

The HOC used in AsyncTypeahead.

menuItemContainer

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 wrap them with this HOC:

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

const TypeaheadMenuItem = menuItemContainer(MenuItem);

<Typeahead
  renderMenu={(results, menuProps) => (
    <Menu {...menuProps}>
      {results.map((result, props) => (
        <TypeaheadMenuItem>
          {result.label}
        </TypeaheadMenuItem>
      ))}
    </Menu>
  )}
/>

tokenContainer

Encapsulates keystroke and outside click behaviors used in Token. Useful if you want completely custom markup for the token.

const MyCustomToken = tokenContainer(props => (
  // Your token code...
));

<Typeahead
  multiple
  options={options}
  renderToken={(option, props, index) => (
    <MyCustomToken onRemove={props.onRemove} option={option} />
  )}
/>