Alternatives

Combobox — Allows the user to browse, search, and make a single selection from a large list of values.
SelectInput — For small lists.

Usage

The Autocomplete has no opinions about what you do when an option is selected.

<Autocomplete
  onChange={(option) => {
    alert('selected ' + option.value);
  }}
  loadOptions={async (inputValue) => {
    await wait(500);
    return [
      { value: '1', label: 'Some option' },
      { value: '2', label: 'Another option' },
    ].filter(({ label }) =>
      label.toLowerCase().includes(inputValue.toLowerCase())
    );
  }}
/>

disabled

Disables the autocomplete.

Edit in Playroom

<Autocomplete onChange={() => {}} loadOptions={() => {}} disabled />

Selecting options

You may want to show the option that the user selected when they are inside a form. You can use value to do this.

Edit in Playroom

let [value, setValue] = useState(null);
return (
  <Autocomplete
    onChange={(option) => {
      setValue(option);
    }}
    value={value}
    loadOptions={async (inputValue) => {
      await wait(500);
      return [
        { value: '1', label: 'Some option' },
        { value: '2', label: 'Another option' },
      ].filter(({ label }) =>
        label.toLowerCase().includes(inputValue.toLowerCase())
      );
    }}
  />
);

AutocompleteField

If you're using the Autocomplete inside a form, you should use the AutocompleteField component. This accepts similar props to other Field components.

Edit in Playroom

let [value, setValue] = useState(null);
return (
  <AutocompleteField
    label="Field label"
    description="Provide instructions that may aid user input"
    invalidMessage="Invalid message reserved for required fields"
    onChange={(option) => {
      setValue(option);
    }}
    value={value}
    loadOptions={async (inputValue) => {
      await wait(500);
      return [
        { value: '1', label: 'Some option' },
        { value: '2', label: 'Another option' },
      ].filter(({ label }) =>
        label.toLowerCase().includes(inputValue.toLowerCase())
      );
    }}
  />
);

Option renderers

You can provide a render function to renderOption to render options in a different way. Three default render functions are exported for various use cases.

Users

Edit in Playroom

<Autocomplete
  onChange={(option) => {
    alert('selected ' + option.label);
  }}
  loadOptions={async (inputValue) => {
    await wait(500);
    return [
      {
        value: '1',
        label: 'Some person',
      },
      {
        value: '2',
        label: 'Another person',
      },
    ].filter(({ label }) =>
      label.toLowerCase().includes(inputValue.toLowerCase())
    );
  }}
  renderOption={userOptionRenderer}
/>

Entities

Edit in Playroom

<Autocomplete
  onChange={(option) => {
    alert('selected ' + option.label);
  }}
  loadOptions={async (inputValue) => {
    await wait(500);
    return [
      { value: '1', label: 'Some person' },
      { value: '2', label: 'Another person' },
    ].filter(({ label }) =>
      label.toLowerCase().includes(inputValue.toLowerCase())
    );
  }}
  renderOption={userOptionRenderer}
/>

Entity Details

Edit in Playroom

<Autocomplete
  onChange={(option) => {
    alert('selected ' + option.label);
  }}
  loadOptions={async (inputValue) => {
    await wait(500);
    return [
      { value: '1', label: 'Some person' },
      { value: '2', label: 'Another person' },
      { value: '3', label: 'Some company' },
    ].filter(({ label }) =>
      label.toLowerCase().includes(inputValue.toLowerCase())
    );
  }}
  renderOption={entityOptionRenderer}
/>

Edit in Playroom

<Autocomplete
  onChange={(option) => {
    alert('selected ' + option.label);
  }}
  loadOptions={async (inputValue) => {
    await wait(500);
    return [
      {
        value: '1',
        label: 'Some person',
        email: 'something@example.com',
        phone: '11111111',
        type: 'Person',
      },
      {
        value: '2',
        label: 'Another person',
        email: 'another@example.com',
        phone: '11111111',
        type: 'Person',
      },
      {
        value: '3',
        label: 'Some company',
        email: 'company@example.com',
        phone: '11111111',
        type: 'Organisation',
      },
    ].filter(({ label }) =>
      label.toLowerCase().includes(inputValue.toLowerCase())
    );
  }}
  renderOption={entityDetailOptionRenderer}
/>