Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/meafmira/react-typeahead-lib
https://github.com/meafmira/react-typeahead-lib
Last synced: about 1 month ago
JSON representation
- Host: GitHub
- URL: https://github.com/meafmira/react-typeahead-lib
- Owner: meafmira
- License: isc
- Created: 2015-08-24T07:04:12.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2015-08-27T08:06:34.000Z (over 9 years ago)
- Last Synced: 2023-08-03T11:39:44.641Z (over 1 year ago)
- Language: JavaScript
- Size: 426 KB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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:
```javascript
var Typeahead = require('react-typeahead').Typeahead;
React.render(
);
```
For a tokenizer typeahead input:
```javascript
var Tokenizer = require('react-typeahead').Tokenizer;
React.render(
);
```
## Examples
* [Basic Typeahead with Topcoat][1]
* [Typeahead Tokenizer with Topcoat][2]
* [Typeahead Tokenizer with simple styling][3]
[1]: http://wookiehangover.github.com/react-typeahead/examples/typeahead-topcoat.html
[2]: http://wookiehangover.github.com/react-typeahead/examples/tokenizer-topcoat.html
[3]: http://wookiehangover.github.com/react-typeahead/examples/TypeaheadTokenizer-simple.html
[4]: http://blog.npmjs.org/post/85484771375/how-to-install-npm
## 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 `` element rather than an `` element
#### props.inputProps
Type: `Object`
Props to pass directly to the `` 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](https://github.com/mattyork/fuzzy).
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.
If provided as a string, it will interpret it as a field name and use that field from each option 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 to `Typeahead.props.maxVisible`.
- `props.selectedIndex`
- The index of the highlighted option for rendering
### Typeahead ([Exposed Component Functions][reactecf])
#### 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 `` 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](https://github.com/mattyork/fuzzy).
#### props.defaultClassNames
Type: `boolean`
Default: true
If false, the default classNames are removed from the tokenizer and the typeahead.
### Tokenizer ([Exposed Component Functions][reactecf])
#### 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][4].
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.
[reactecf]: https://facebook.github.io/react/tips/expose-component-functions.html