# 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](#components) - [``](#typeahead) - [``](#asynctypeahead) - [``](#highlighter) - [``](#menu) - [``](#menuitem) - [``](#typeaheadmenu) - [``](#token) - [Higher-Order Components](#higher-order-components) - [`asyncContainer`](#asynccontainer) - [`menuItemContainer`](#menuitemcontainer) - [`tokenContainer`](#tokencontainer) ## Components Only a subset of props are documented below, primarily those expecting functions. See the [props documentation](Props.md) for the full list of options. ### `` 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: ```js allowNew(results: Array, props: Object): bool ``` ##### `filterBy: Array|Function` See full documentation in the [Filtering section](Filtering.md#filterby-arraystring--function). ##### `labelKey: String|Function` See full documentation in the [Rendering section](Rendering.md#labelkey-string--function). ##### `renderMenu: Function`, `renderMenuItemChildren: Function`, and `renderToken: Function` See full documentation in the [Rendering section](Rendering.md#rendermenuresults-arrayobject--string-menuprops-object). ##### `onChange(selected: Array)` 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. ### `` 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. ```jsx { 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: ```jsx 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. ### `` 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`. ```jsx ( {option[props.labelKey]} )} /> ``` ### `` Provides the markup for a Bootstrap menu, along with some extra functionality for specifying a label when there are no results. ### `` 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. ### `` 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. ### `` Individual token component, most commonly for use within `renderToken` to customize the `Token` contents. ## Higher-Order Components ### `asyncContainer` The HOC used in [`AsyncTypeahead`](#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: ```jsx import {MenuItem} from 'react-bootstrap'; import {Menu, menuItemContainer, Typeahead} from 'react-bootstrap-typeahead'; const TypeaheadMenuItem = menuItemContainer(MenuItem); ( {results.map((result, props) => ( {result.label} ))} )} /> ``` ### `tokenContainer` Encapsulates keystroke and outside click behaviors used in `Token`. Useful if you want completely custom markup for the token. ```jsx const MyCustomToken = tokenContainer(props => ( // Your token code... )); ( )} /> ```