Autocomplete

View on GitHub

Introduction

The Autocomplete components renders a filterable list of options in a Popover — it does not render the text input. If you need a combination with a text input and trigger button, take a look at the Combobox component. This component is mainly used to create type aheads

You might not need Autocomplete

In some cases you might be better off using Combobox or SelectMenu.

The autocomplete component combines a set of external libraries

  • Uses Downshift for autocomplete
  • Uses react-tiny-virtual-list for performant list rendering
  • Uses fuzzaldrin-plus for fuzzy filtering

Default example

<Autocomplete
  title="Fruits"
  onChange={(changedItem) => console.log(changedItem)}
  items={['Apple', 'Apricot', 'Banana', 'Cherry', 'Cucumber']}
>
  {(props) => {
    const { getInputProps, getRef, inputValue } = props
    return (
      <TextInput
        placeholder="Fruits"
        value={inputValue}
        innerRef={getRef}
        {...getInputProps()}
      />
    )
  }}
</Autocomplete>
code Hide code

Using children prop

There is no difference between using this syntax and the above syntax.

<Autocomplete
  title="Fruits"
  onChange={changedItem => console.log(changedItem)}
  items={['Apple', 'Apricot', 'Banana', 'Cherry', 'Cucumber']}
  children={(props) => {
    const { getInputProps, getRef, inputValue } = props
    return (
      <TextInput
        placeholder="Fruits"
        value={inputValue}
        innerRef={getRef}
        {...getInputProps()}
      />
    )
  }}
/>
code Hide code

Open on focus

Get the openMenu prop to manually open the menu on certain events such as onFocus.

<Autocomplete
  title="Fruits"
  onChange={changedItem => console.log(changedItem)}
  items={['Apple', 'Apricot', 'Banana', 'Cherry', 'Cucumber']}
>
  {(props) => {
    const { getInputProps, getRef, inputValue, openMenu } = props
    return (
      <TextInput
        placeholder="Open on focus"
        value={inputValue}
        innerRef={getRef}
        {...getInputProps({
          onFocus: () => {
            openMenu()
          }
        })}
      />
    )
  }}
</Autocomplete>
code Hide code

Results with an external trigger

<Autocomplete
  title="Fruits"
  onChange={changedItem => console.log(changedItem)}
  items={['Apple', 'Apricot', 'Banana', 'Cherry', 'Cucumber']}
>
  {({
    getInputProps,
    getButtonProps,
    getRef,
    inputValue,
    toggleMenu
  }) => (
    <Pane innerRef={getRef} display="inline-block">
      <TextInput
        placeholder="Trigger with button"
        value={inputValue}
        {...getInputProps()}
      />
      <Button onClick={toggleMenu} {...getButtonProps()}>
        Trigger
      </Button>
    </Pane>
  )}
</Autocomplete>
code Hide code

Fully featured example

Full width with flex and options title, onFocus, filtering, and button to trigger the autocomplete. Note that this is very similar the Combobox component. Consider using that component before using the Autocomplete component directly.

<Autocomplete
  title="Custom title"
  onChange={changedItem => console.log(changedItem)}
  items={['Apple', 'Apricot', 'Banana', 'Cherry', 'Cucumber']}
>
  {({
    key,
    getInputProps,
    getButtonProps,
    getRef,
    inputValue,
    openMenu,
    toggleMenu
  }) => (
    <Pane
      key={key}
      innerRef={getRef}
      display="flex"
    >
      <TextInput
        flex="1"
        placeholder="Many Options!"
        value={inputValue}
        onFocus={openMenu}
        {...getInputProps()}
      />
      <Button onClick={toggleMenu} {...getButtonProps()}>
        Trigger
      </Button>
    </Pane>
  )}
</Autocomplete>
code Hide code

Autocomplete Props

This component composes downshift

titleunion
This prop can be either a string or a Node. It will provide a title for the items
itemsarrayrequired
An array of items to be used as options for the select
selectedItemany
The selected Item to be shown on the autocomplete
defaultSelectedItemany
The selected item to be selected & shown by default on the autocomplete
itemToStringfunc = i => (i ? String(i) : '')
In case the array of items is not an array of strings, this function is used on each item to return the string that will be shown on the filter
childrenfuncrequired
Function that will render the 'filter' component.
itemSizenumber = 32
The height of each item in the list Because the list is virtualized this is required beforehand.
renderItemfunc = props => <AutocompleteItem {...props} />
Function that returns a component to render the item
positionenum
Value type: Object.keys(Position)
The position of the Popover the Autocomplete is rendered in.
itemsFilterfunc = (items, input) => fuzzaldrin.filter(items, input)
A function that is used to filter the items. It should return a subset of the initial items. By default the "fuzzaldrin-plus" package is used.
isFilterDisabledbool = false
Prop that enables and disables filtering True: Enables Filtering False: Disables Filtering
popoverMinWidthnumber = 240
Defines the minimum height the results container will be
popoverMaxHeightnumber = 240
Defines the maximum height the results container will be