react-typeahead
A typeahead/autocomplete component for React
react-typeahead is a javascript library that provides a react-based typeahead, or autocomplete text entry, as well as a "typeahead tokenizer", a typeahead that allows you to select multiple results.
Usage
For a typeahead input:
var Typeahead = require('react-typeahead').Typeahead;
React.render(
<Typeahead
options={['John', 'Paul', 'George', 'Ringo']}
maxVisible={2}
/>
);
For a tokenizer typeahead input:
var Tokenizer = require('react-typeahead').Tokenizer;
React.render(
<Tokenizer
options={['John', 'Paul', 'George', 'Ringo']}
onTokenAdd={function(token) {
console.log('token added: ', token);
}}
/>
);
Examples
- Basic Typeahead with Topcoat
- Typeahead Tokenizer with Topcoat
- Typeahead Tokenizer with simple styling
API
Typeahead(props)
Type: React Component
Basic typeahead input and results list.
props.options
Type: Array
Default: []
An array supplied to the filtering function. Can be a list of strings or a list of arbitrary objects. In the latter case, filterOption
and displayOption
should be provided.
props.defaultValue
Type: String
A default value used when the component has no value. If it matches any options a option list will show.
props.value
Type: String
Specify a value for the text input.
props.maxVisible
Type: Number
Limit the number of options rendered in the results list.
props.customClasses
Type: Object
Allowed Keys: input
, results
, listItem
, listAnchor
, hover
An object containing custom class names for child elements. Useful for integrating with 3rd party UI kits.
props.placeholder
Type: String
Placeholder text for the typeahead input.
props.textarea
Type: Boolean
Set to true
to use a <textarea>
element rather than an <input>
element
props.inputProps
Type: Object
Props to pass directly to the <input>
element.
props.onKeyDown
Type: Function
Event handler for the keyDown
event on the typeahead input.
props.onKeyUp
Type: Function
Event handler for the keyUp
event on the typeahead input.
props.onBlur
Type: Function
Event handler for the blur
event on the typeahead input.
props.onFocus
Type: Function
Event handler for the focus
event on the typeahead input.
props.onOptionSelected
Type: Function
Event handler triggered whenever a user picks an option.
props.filterOption
Type: String
or Function
A function to filter the provided options
based on the current input value. For each option, receives (inputValue, option)
. If not supplied, defaults to fuzzy string matching.
If provided as a string, it will interpret it as a field name and fuzzy filter on that field of each option object.
props.displayOption
Type: String
or Function
A function to map an option onto a string for display in the list. Receives (option, index)
where index is relative to the results list, not all the options. Must return a string or an element.
If provided as a string, it will interpret it as a field name and use that field from each option object.
If provided function returns an element, toString method of the option is used to determine the value set to the input and passed to onOptionSelected. If toString is not implemented, the value will most likely be [object Object]
.
props.formInputOption
Type: String
or Function
A function to map an option onto a string to include in HTML forms (see props.name
). Receives (option)
as arguments. Must return a string.
If specified as a string, it will interpret it as a field name and use that field from each option object.
If not specified, it will fall back onto the semantics described in props.displayOption
.
This option is ignored if you don't specify the name
prop. It is required if you both specify the name
prop and are using non-string options. It is optional otherwise.
props.defaultClassNames
Type: boolean
Default: true
If false, the default classNames are removed from the typeahead.
props.customListComponent
Type: React Component
A React Component that renders the list of typeahead results. This replaces the default list of results.
This component receives the following props :
Passed through
props.displayOptions
props.customClasses
props.onOptionSelected
Created or modified
-
props.options
- This is the Typeahead's
props.options
filtered and limited toTypeahead.props.maxVisible
.
- This is the Typeahead's
-
props.selectionIndex
- The index of the highlighted option for rendering
Exposed Component Functions)
Typeahead (typeahead.focus
Focuses the typeahead input.
Tokenizer(props)
Type: React Component
Typeahead component that allows for multiple options to be selected.
props.options
Type: Array
Default: []
An array supplied to the filter function.
props.maxVisible
Type: Number
Limit the number of options rendered in the results list.
props.name
Type: String
The name for HTML forms to be used for submitting the tokens' values array.
props.customClasses
Type: Object
Allowed Keys: input
, results
, listItem
, listAnchor
, typeahead
An object containing custom class names for child elements. Useful for integrating with 3rd party UI kits.
props.placeholder
Type: String
Placeholder text for the typeahead input.
props.inputProps
Type: Object
Props to pass directly to the <input>
element.
props.onKeyDown
Type: Function
Event handler for the keyDown
event on the typeahead input.
props.onKeyUp
Type: Function
Event handler for the keyUp
event on the typeahead input.
props.onBlur
Type: Function
Event handler for the blur
event on the typeahead input.
props.onFocus
Type: Function
Event handler for the focus
event on the typeahead input.
props.defaultSelected
Type: Array
A set of values of tokens to be loaded on first render.
props.onTokenRemove
Type: Function
Params: (removedToken)
Event handler triggered whenever a token is removed.
props.onTokenAdd
Type: Function
Params: (addedToken)
Event handler triggered whenever a token is removed.
props.displayOption
Type: String
or Function
A function to map an option onto a string for display in the list. Receives (option, index)
where index is relative to the results list, not all the options. Must return a string.
If provided as a string, it will interpret it as a field name and use that field from each option object.
props.filterOption
Type: Function
A function to filter the provided options
based on the current input value. For each option, receives (inputValue, option)
. If not supplied, defaults to fuzzy string matching.
props.defaultClassNames
Type: boolean
Default: true
If false, the default classNames are removed from the tokenizer and the typeahead.
Exposed Component Functions)
Tokenizer (tokenizer.focus
Focuses the tokenizer input.
tokenizer.getSelectedTokens
Type: Function
A function to return the currently selected tokens.
Developing
Setting Up
You will need npm
to develop on react-typeahead. Installing npm.
Once that's done, to get started, run npm install
in your checkout directory.
This will install all the local development dependences, such as gulp
and mocha
Testing
react-typeahead uses mocha for unit tests and gulp for running them. Large changes should include unittests.
After updating or creating new tests, run npm run-script build-test
to regenerate the
test package.
Once that's done, running the tests is easy with gulp
:
> gulp test
[00:17:25] Using gulpfile ~/src/react-typeahead/gulpfile.js
[00:17:25] Starting 'test'...
․․․․․․․․․․․․․․․
15 passing (43ms)
[00:17:25] Finished 'test' after 448 ms
[00:17:25] Starting 'default'...
[00:17:25] Finished 'default' after 6.23 μs
Contributing
Basically, fork the repository and send a pull request. It can be difficult to review these, so here are some general rules to follow for getting your PR accepted more quickly:
- All new properties and exposed component function should be documented in the README.md
- Break your changes into smaller, easy to understand commits.
- Send separate PRs for each commit when possible.
- Feel free to rebase, merge, and rewrite commits to make them more readible.
- Add comments explaining anything that's not painfully obvious.
- Add unittests for your change if possible.