1 | # Rendering
|
2 | `react-bootstrap-typeahead` is intended to work with standard [Bootstrap](http://getbootstrap.com/) components and styles. It provides basic rendering for your data by default, but also allows for more advanced options should the need arise.
|
3 |
|
4 | ### `labelKey: String|Function`
|
5 |
|
6 | The `labelKey` prop specifies the string that will be used for searching and rendering options and selections. If set to a string (default), it will use that property of the data option. You can also pass in a function to do something like concatenate multiple data properties.
|
7 |
|
8 | #### `String` (default: `'label'`)
|
9 | Passing a string value specifies which property on your data object to use. If you pass an array of strings as your data, `labelKey` is ignored.
|
10 |
|
11 | #### `Function(option: Object|String)`
|
12 | Pass in a function to create a custom string without modifying your data. Note: the return value *must* be a string.
|
13 |
|
14 | ```jsx
|
15 | // Menu items and selections will display, eg: "Elvin Jones".
|
16 | <Typeahead
|
17 | labelKey={option => `${option.firstName} ${option.lastName}`}
|
18 | options={[
|
19 | {firstName: 'Art', lastName: 'Blakey'},
|
20 | {firstName: 'Jimmy', lastName: 'Cobb'},
|
21 | {firstName: 'Elvin', lastName: 'Jones'},
|
22 | {firstName: 'Max', lastName: 'Roach'},
|
23 | {firstName: 'Tony', lastName: 'Williams'},
|
24 | ]}
|
25 | />
|
26 | ```
|
27 |
|
28 | ### `renderInput(inputProps: Object, state: Object)`
|
29 | Provides flexibility for rendering the typeahead's input. `inputProps` are any input-relevant props passed down from the `Typeahead` component. You can also just set props directly on your `input`.
|
30 |
|
31 | ```jsx
|
32 | <Typeahead
|
33 | options={options}
|
34 | renderInput={({ inputRef, referenceElementRef, ...inputProps }) => (
|
35 | <CustomInput
|
36 | {...inputProps}
|
37 | ref={(input) => {
|
38 | // Be sure to correctly handle these refs. In many cases, both can simply receive
|
39 | // the underlying input node, but `referenceElementRef can receive a wrapper node if
|
40 | // your custom input is more complex (See TypeaheadInputMulti for an example).
|
41 | inputRef(input);
|
42 | referenceElementRef(input);
|
43 | }}
|
44 | />
|
45 | )}
|
46 | />
|
47 | ```
|
48 |
|
49 | #### `renderInput` gotchas
|
50 | - Your input component must correctly apply the `inputRef` and `referenceElementRef` properties passed to `renderInput` (see example code above). Both are callback refs that expect DOM elements. `inputRef` is used internally to control aspects of the component like blur and focus states, and must receive the `input` node from your component. `referenceElementRef` is used by popper.js to position the menu and in many cases is also simply the input node itself. In case of a more complex input (eg: multi-select/tokenizer), the reference element may be a container element, hence the need for separate refs.
|
51 | - To take advantage of hinting functionality, use the `Hint` component. Alternatively, you can use the `useHint` hook and apply your own hint markup.
|
52 |
|
53 | ### `renderMenu(results: Array<Object|String>, menuProps: Object, state: Object)`
|
54 | Provides flexibility for rendering the typeahead's menu. `results` are the subset of options after they have been filtered and paginated. `menuProps` are any menu-relevant props passed down from the `Typeahead` component. You can also just set props directly on your `Menu`.
|
55 |
|
56 | Along with stylistic customization, the `renderMenu` hook allows you to do things like re-sort or group your data. Note that if you manipulate data in this way, you *must* use either the provided `MenuItem` component or the [appropriate hook or HOC](API.md#useitem--withitem) to ensure proper behavior.
|
57 |
|
58 | ```jsx
|
59 | <Typeahead
|
60 | options={options}
|
61 | renderMenu={(results, menuProps) => (
|
62 | <Menu {...menuProps}>
|
63 | {results.map((result, index) => (
|
64 | <MenuItem option={result} position={index}>
|
65 | {result.label}
|
66 | </MenuItem>
|
67 | ))}
|
68 | </Menu>
|
69 | )}
|
70 | />
|
71 | ```
|
72 |
|
73 | #### `renderMenu` gotchas
|
74 | - It is highly recommended that you use the `Menu` component included with the package. If you choose to use your own component, you will need to properly consume the `innerRef` prop passed down as part of `menuProps` or your menu will not be properly positioned.
|
75 | - If you want to allow custom options or pagination, you will need to render these menu items yourself. If present, they should be the last two items in the `results` array. See the [TypeaheadMenu](https://github.com/ericgio/react-bootstrap-typeahead/blob/master/src/components/TypeaheadMenu.js) component for an example of how to handle rendering.
|
76 |
|
77 | ### `renderMenuItemChildren(option: Object|String, props: Object, index: Number)`
|
78 | Allows you to control the contents of a menu item. Your function will be passed an item from your `options` array, the `TypeaheadMenu` props, and the item's index within the array:
|
79 |
|
80 | ```jsx
|
81 | <Typeahead
|
82 | options={options}
|
83 | renderMenuItemChildren={(option, props, index) => {
|
84 | /* Render custom contents here. */
|
85 | }}
|
86 | />
|
87 | ```
|
88 |
|
89 | ### `renderToken(option: Object|String, props: Object, index: Number)`
|
90 | Provides the ability to customize rendering of tokens when multiple selections are enabled. This callback is ignored if `multiple=false`.
|
91 |
|
92 | ```jsx
|
93 | <Typeahead
|
94 | ...
|
95 | multiple
|
96 | renderToken={(option, props, index) => {
|
97 | /* Render custom token here. */
|
98 | }}
|
99 | />
|
100 | ```
|
101 |
|
102 | Be careful when using `renderToken`, since you will need to handle things like disabling the tokens and removing them (via `props.onRemove`) yourself. It is highly recommended that you use the provided `Token` component. If you want to use a completely custom token, use either the provided [hook or HOC](API.md#usetoken--withtoken) to retain keystroke behaviors.
|
103 |
|
104 | [Next: Public Methods](Methods.md)
|