Skip to content

Latest commit

 

History

History
104 lines (86 loc) · 5.46 KB

Rendering.md

File metadata and controls

104 lines (86 loc) · 5.46 KB
Raw

Rendering

react-bootstrap-typeahead is intended to work with standard Bootstrap components and styles. It provides basic rendering for your data by default, but also allows for more advanced options should the need arise.

labelKey: String|Function

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.

String (default: 'label')

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.

Function(option: Object|String)

Pass in a function to create a custom string without modifying your data. Note: the return value must be a string.

// Menu items and selections will display, eg: "Elvin Jones".
<Typeahead
  labelKey={option => `${option.firstName} ${option.lastName}`}
  options={[
    {firstName: 'Art', lastName: 'Blakey'},
    {firstName: 'Jimmy', lastName: 'Cobb'},
    {firstName: 'Elvin', lastName: 'Jones'},
    {firstName: 'Max', lastName: 'Roach'},
    {firstName: 'Tony', lastName: 'Williams'},
  ]}
/>

renderInput(inputProps: Object, state: Object)

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.

<Typeahead
  options={options}
  renderInput={({ inputRef, referenceElementRef, ...inputProps }) => (
    <CustomInput
      {...inputProps}
      ref={(input) => {
        // Be sure to correctly handle these refs. In many cases, both can simply receive
        // the underlying input node, but `referenceElementRef can receive a wrapper node if
        // your custom input is more complex (See TypeaheadInputMulti for an example).
        inputRef(input);
        referenceElementRef(input);
      }}
    />
  )}
/>

renderInput gotchas

  • 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.
  • To take advantage of hinting functionality, use the Hint component. Alternatively, you can use the useHint hook and apply your own hint markup.

renderMenu(results: Array<Object|String>, menuProps: Object, state: Object)

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.

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 to ensure proper behavior.

<Typeahead
  options={options}
  renderMenu={(results, menuProps) => (
    <Menu {...menuProps}>
      {results.map((result, index) => (
        <MenuItem option={result} position={index}>
          {result.label}
        </MenuItem>
      ))}
    </Menu>
  )}
/>

renderMenu gotchas

  • 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.
  • 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 component for an example of how to handle rendering.

renderMenuItemChildren(option: Object|String, props: Object, index: Number)

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:

<Typeahead
  options={options}
  renderMenuItemChildren={(option, props, index) => {
    /* Render custom contents here. */
  }}
/>

renderToken(option: Object|String, props: Object, index: Number)

Provides the ability to customize rendering of tokens when multiple selections are enabled. This callback is ignored if multiple=false.

<Typeahead
  ...
  multiple
  renderToken={(option, props, index) => {
    /* Render custom token here. */
  }}
/>

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 to retain keystroke behaviors.

Next: Public Methods