alpha

SearchAutocomplete

A SearchAutocomplete is a searchfield that supports a dynamic list of suggestions.

installyarn add @react-spectrum/autocomplete
version3.0.0-alpha.6
usageimport {SearchAutocomplete, Section, Item} from '@react-spectrum/autocomplete'

Example#


<SearchAutocomplete label="Search with Autocomplete">
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>
<SearchAutocomplete label="Search with Autocomplete">
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>
<SearchAutocomplete label="Search with Autocomplete">
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>

Content#


SearchAutocomplete follows the Collection Components API, accepting both static and dynamic collections. Similar to ComboBox, SearchAutocomplete accepts <Item> elements as children, each with a key prop. Basic usage of SearchAutocomplete, seen in the example above, shows multiple options populated with a string. Static collections, as in this example, can be used when the full list of options is known ahead of time.

Dynamic collections, as shown below, can be used when the options come from an external data source such as an API call, or update over time. Providing the data in this way allows SearchAutocomplete to automatically cache the rendering of each item, which dramatically improves performance.

As seen below, an iterable list of options is passed to the SearchAutocomplete using the defaultItems prop.

function Example() {
  let options = [
    {id: 1, name: 'Aerospace'},
    {id: 2, name: 'Mechanical'},
    {id: 3, name: 'Civil'},
    {id: 4, name: 'Biomedical'},
    {id: 5, name: 'Nuclear'},
    {id: 6, name: 'Industrial'},
    {id: 7, name: 'Chemical'},
    {id: 8, name: 'Agricultural'},
    {id: 9, name: 'Electrical'}
  ];

  return (
    <SearchAutocomplete
      label="Search engineering majors"
      defaultItems={options}>
      {item => <Item>{item.name}</Item>}
    </SearchAutocomplete>
  );
}
function Example() {
  let options = [
    {id: 1, name: 'Aerospace'},
    {id: 2, name: 'Mechanical'},
    {id: 3, name: 'Civil'},
    {id: 4, name: 'Biomedical'},
    {id: 5, name: 'Nuclear'},
    {id: 6, name: 'Industrial'},
    {id: 7, name: 'Chemical'},
    {id: 8, name: 'Agricultural'},
    {id: 9, name: 'Electrical'}
  ];

  return (
    <SearchAutocomplete
      label="Search engineering majors"
      defaultItems={options}>
      {item => <Item>{item.name}</Item>}
    </SearchAutocomplete>
  );
}
function Example() {
  let options = [
    {
      id: 1,
      name: 'Aerospace'
    },
    {
      id: 2,
      name: 'Mechanical'
    },
    {
      id: 3,
      name: 'Civil'
    },
    {
      id: 4,
      name: 'Biomedical'
    },
    {
      id: 5,
      name: 'Nuclear'
    },
    {
      id: 6,
      name: 'Industrial'
    },
    {
      id: 7,
      name: 'Chemical'
    },
    {
      id: 8,
      name:
        'Agricultural'
    },
    {
      id: 9,
      name: 'Electrical'
    }
  ];

  return (
    <SearchAutocomplete
      label="Search engineering majors"
      defaultItems={options}
    >
      {(item) => (
        <Item>
          {item.name}
        </Item>
      )}
    </SearchAutocomplete>
  );
}

Alternatively, passing your list of options to SearchAutocomplete's items prop will cause the list of items to be controlled, useful for when you want to provide your own filtering logic. See the Custom Filtering section for more detail.

Internationalization#

To internationalize a SearchAutocomplete, a localized string should be passed to the children of each Item. For languages that are read right-to-left (e.g. Hebrew and Arabic), the layout of the SearchAutocomplete is automatically flipped.

Labeling#


SearchAutocomplete can be labeled using the label prop. If the SearchAutocomplete is a required field, the isRequired and necessityIndicator props can be used to show a required state.

<SearchAutocomplete
  label="Favorite Animal"
  isRequired
  necessityIndicator="icon"
>
  <Item>Red Panda</Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>
<SearchAutocomplete
  label="Favorite Animal"
  isRequired
  necessityIndicator="icon"
>
  <Item>Red Panda</Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>
<SearchAutocomplete
  label="Favorite Animal"
  isRequired
  necessityIndicator="icon"
>
  <Item>
    Red Panda
  </Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>
<SearchAutocomplete
  label="Favorite Animal"
  isRequired
  necessityIndicator="label"
>
  <Item>Red Panda</Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>
<SearchAutocomplete
  label="Favorite Animal"
  isRequired
  necessityIndicator="label"
>
  <Item>Red Panda</Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>
<SearchAutocomplete
  label="Favorite Animal"
  isRequired
  necessityIndicator="label"
>
  <Item>
    Red Panda
  </Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>
<SearchAutocomplete label="Favorite Animal" necessityIndicator="label">
  <Item>Red Panda</Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>
<SearchAutocomplete
  label="Favorite Animal"
  necessityIndicator="label"
>
  <Item>Red Panda</Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>
<SearchAutocomplete
  label="Favorite Animal"
  necessityIndicator="label"
>
  <Item>
    Red Panda
  </Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>

Accessibility#

If a visible label isn't specified, an aria-label must be provided to the SearchAutocomplete for accessibility. If the field is labeled by a separate element, an aria-labelledby prop must be provided using the id of the labeling element instead.

Internationalization#

In order to internationalize a SearchAutocomplete, a localized string should be passed to the label or aria-label prop. When the necessityIndicator prop is set to "label", a localized string will be provided for "(required)" or "(optional)" automatically.

Sections#


SearchAutocomplete supports sections in order to group options. Sections can be used by wrapping groups of items in a Section element. Each Section takes a title and key prop.

Static items#

<SearchAutocomplete label="Preferred fruit or vegetable">
  <Section title="Fruit">
    <Item key="Apple">Apple</Item>
    <Item key="Banana">Banana</Item>
    <Item key="Orange">Orange</Item>
    <Item key="Honeydew">Honeydew</Item>
    <Item key="Grapes">Grapes</Item>
    <Item key="Watermelon">Watermelon</Item>
    <Item key="Cantaloupe">Cantaloupe</Item>
    <Item key="Pear">Pear</Item>
  </Section>
  <Section title="Vegetable">
    <Item key="Cabbage">Cabbage</Item>
    <Item key="Broccoli">Broccoli</Item>
    <Item key="Carrots">Carrots</Item>
    <Item key="Lettuce">Lettuce</Item>
    <Item key="Spinach">Spinach</Item>
    <Item key="Bok Choy">Bok Choy</Item>
    <Item key="Cauliflower">Cauliflower</Item>
    <Item key="Potatoes">Potatoes</Item>
  </Section>
</SearchAutocomplete>
<SearchAutocomplete label="Preferred fruit or vegetable">
  <Section title="Fruit">
    <Item key="Apple">Apple</Item>
    <Item key="Banana">Banana</Item>
    <Item key="Orange">Orange</Item>
    <Item key="Honeydew">Honeydew</Item>
    <Item key="Grapes">Grapes</Item>
    <Item key="Watermelon">Watermelon</Item>
    <Item key="Cantaloupe">Cantaloupe</Item>
    <Item key="Pear">Pear</Item>
  </Section>
  <Section title="Vegetable">
    <Item key="Cabbage">Cabbage</Item>
    <Item key="Broccoli">Broccoli</Item>
    <Item key="Carrots">Carrots</Item>
    <Item key="Lettuce">Lettuce</Item>
    <Item key="Spinach">Spinach</Item>
    <Item key="Bok Choy">Bok Choy</Item>
    <Item key="Cauliflower">Cauliflower</Item>
    <Item key="Potatoes">Potatoes</Item>
  </Section>
</SearchAutocomplete>
<SearchAutocomplete label="Preferred fruit or vegetable">
  <Section title="Fruit">
    <Item key="Apple">
      Apple
    </Item>
    <Item key="Banana">
      Banana
    </Item>
    <Item key="Orange">
      Orange
    </Item>
    <Item key="Honeydew">
      Honeydew
    </Item>
    <Item key="Grapes">
      Grapes
    </Item>
    <Item key="Watermelon">
      Watermelon
    </Item>
    <Item key="Cantaloupe">
      Cantaloupe
    </Item>
    <Item key="Pear">
      Pear
    </Item>
  </Section>
  <Section title="Vegetable">
    <Item key="Cabbage">
      Cabbage
    </Item>
    <Item key="Broccoli">
      Broccoli
    </Item>
    <Item key="Carrots">
      Carrots
    </Item>
    <Item key="Lettuce">
      Lettuce
    </Item>
    <Item key="Spinach">
      Spinach
    </Item>
    <Item key="Bok Choy">
      Bok Choy
    </Item>
    <Item key="Cauliflower">
      Cauliflower
    </Item>
    <Item key="Potatoes">
      Potatoes
    </Item>
  </Section>
</SearchAutocomplete>

Dynamic items#

Sections used with dynamic items are populated from a hierarchical data structure. Please note that Section takes an array of data using the items prop only.

function Example() {
  let options = [
    {
      name: 'Fruit',
      children: [
        { name: 'Apple' },
        { name: 'Banana' },
        { name: 'Orange' },
        { name: 'Honeydew' },
        { name: 'Grapes' },
        { name: 'Watermelon' },
        { name: 'Cantaloupe' },
        { name: 'Pear' }
      ]
    },
    {
      name: 'Vegetable',
      children: [
        { name: 'Cabbage' },
        { name: 'Broccoli' },
        { name: 'Carrots' },
        { name: 'Lettuce' },
        { name: 'Spinach' },
        { name: 'Bok Choy' },
        { name: 'Cauliflower' },
        { name: 'Potatoes' }
      ]
    }
  ];

  return (
    <SearchAutocomplete
      label="Preferred fruit or vegetable"
      defaultItems={options}
    >
      {(item) => (
        <Section key={item.name} items={item.children} title={item.name}>
          {(item) => (
            <Item key={item.name}>
              {item.name}
            </Item>
          )}
        </Section>
      )}
    </SearchAutocomplete>
  );
}
function Example() {
  let options = [
    {
      name: 'Fruit',
      children: [
        { name: 'Apple' },
        { name: 'Banana' },
        { name: 'Orange' },
        { name: 'Honeydew' },
        { name: 'Grapes' },
        { name: 'Watermelon' },
        { name: 'Cantaloupe' },
        { name: 'Pear' }
      ]
    },
    {
      name: 'Vegetable',
      children: [
        { name: 'Cabbage' },
        { name: 'Broccoli' },
        { name: 'Carrots' },
        { name: 'Lettuce' },
        { name: 'Spinach' },
        { name: 'Bok Choy' },
        { name: 'Cauliflower' },
        { name: 'Potatoes' }
      ]
    }
  ];

  return (
    <SearchAutocomplete
      label="Preferred fruit or vegetable"
      defaultItems={options}
    >
      {(item) => (
        <Section
          key={item.name}
          items={item.children}
          title={item.name}
        >
          {(item) => (
            <Item key={item.name}>{item.name}</Item>
          )}
        </Section>
      )}
    </SearchAutocomplete>
  );
}
function Example() {
  let options = [
    {
      name: 'Fruit',
      children: [
        {
          name: 'Apple'
        },
        {
          name: 'Banana'
        },
        {
          name: 'Orange'
        },
        {
          name:
            'Honeydew'
        },
        {
          name: 'Grapes'
        },
        {
          name:
            'Watermelon'
        },
        {
          name:
            'Cantaloupe'
        },
        { name: 'Pear' }
      ]
    },
    {
      name: 'Vegetable',
      children: [
        {
          name: 'Cabbage'
        },
        {
          name:
            'Broccoli'
        },
        {
          name: 'Carrots'
        },
        {
          name: 'Lettuce'
        },
        {
          name: 'Spinach'
        },
        {
          name:
            'Bok Choy'
        },
        {
          name:
            'Cauliflower'
        },
        {
          name:
            'Potatoes'
        }
      ]
    }
  ];

  return (
    <SearchAutocomplete
      label="Preferred fruit or vegetable"
      defaultItems={options}
    >
      {(item) => (
        <Section
          key={item.name}
          items={item
            .children}
          title={item
            .name}
        >
          {(item) => (
            <Item
              key={item
                .name}
            >
              {item.name}
            </Item>
          )}
        </Section>
      )}
    </SearchAutocomplete>
  );
}

Asynchronous loading#


SearchAutocomplete supports loading data asynchronously, and will display a progress circle reflecting the current load state, set by the loadingState prop. It also supports infinite scrolling to load more data on demand as the user scrolls, via the onLoadMore prop.

This example uses the useAsyncList hook to handle loading the data. See the docs for more information.

import {useAsyncList} from '@react-stately/data';

function AsyncLoadingExample() {
  let list = useAsyncList({
    async load({ signal, cursor, filterText }) {
      if (cursor) {
        cursor = cursor.replace(/^http:\/\//i, 'https://');
      }

      // If no cursor is available, then we're loading the first page,
      // filtering the results returned via a query string that
      // mirrors the SearchAutocomplete input text.
      // Otherwise, the cursor is the next URL to load,
      // as returned from the previous page.
      let res = await fetch(
        cursor || `https://swapi.py4e.com/api/people/?search=${filterText}`,
        { signal }
      );
      let json = await res.json();

      return {
        items: json.results,
        cursor: json.next
      };
    }
  });

  return (
    <SearchAutocomplete
      label="Star Wars Character Lookup"
      items={list.items}
      inputValue={list.filterText}
      onInputChange={list.setFilterText}
      loadingState={list.loadingState}
      onLoadMore={list.loadMore}
    >
      {(item) => <Item key={item.name}>{item.name}</Item>}
    </SearchAutocomplete>
  );
}
import {useAsyncList} from '@react-stately/data';

function AsyncLoadingExample() {
  let list = useAsyncList({
    async load({ signal, cursor, filterText }) {
      if (cursor) {
        cursor = cursor.replace(/^http:\/\//i, 'https://');
      }

      // If no cursor is available, then we're loading the first page,
      // filtering the results returned via a query string that
      // mirrors the SearchAutocomplete input text.
      // Otherwise, the cursor is the next URL to load,
      // as returned from the previous page.
      let res = await fetch(
        cursor ||
          `https://swapi.py4e.com/api/people/?search=${filterText}`,
        { signal }
      );
      let json = await res.json();

      return {
        items: json.results,
        cursor: json.next
      };
    }
  });

  return (
    <SearchAutocomplete
      label="Star Wars Character Lookup"
      items={list.items}
      inputValue={list.filterText}
      onInputChange={list.setFilterText}
      loadingState={list.loadingState}
      onLoadMore={list.loadMore}
    >
      {(item) => <Item key={item.name}>{item.name}</Item>}
    </SearchAutocomplete>
  );
}
import {useAsyncList} from '@react-stately/data';

function AsyncLoadingExample() {
  let list =
    useAsyncList({
      async load(
        {
          signal,
          cursor,
          filterText
        }
      ) {
        if (cursor) {
          cursor = cursor
            .replace(
              /^http:\/\//i,
              'https://'
            );
        }

        // If no cursor is available, then we're loading the first page,
        // filtering the results returned via a query string that
        // mirrors the SearchAutocomplete input text.
        // Otherwise, the cursor is the next URL to load,
        // as returned from the previous page.
        let res =
          await fetch(
            cursor ||
              `https://swapi.py4e.com/api/people/?search=${filterText}`,
            { signal }
          );
        let json =
          await res
            .json();

        return {
          items:
            json.results,
          cursor:
            json.next
        };
      }
    });

  return (
    <SearchAutocomplete
      label="Star Wars Character Lookup"
      items={list.items}
      inputValue={list
        .filterText}
      onInputChange={list
        .setFilterText}
      loadingState={list
        .loadingState}
      onLoadMore={list
        .loadMore}
    >
      {(item) => (
        <Item
          key={item.name}
        >
          {item.name}
        </Item>
      )}
    </SearchAutocomplete>
  );
}

Validation#


SearchAutocomplete can display a validation state to communicate to the user whether the current value is valid or invalid. Implement your own validation logic in your app and pass either "valid" or "invalid" to the SearchAutocomplete via the validationState prop.

The example below illustrates how one would validate if the user has entered a valid email into the SearchAutocomplete.

function Example() {
  let [value, setValue] = React.useState('me@email.com');
  let isValid = React.useMemo(
    () => /^\w+([\.-]?\w+)*@\w+([\.-]?\w+)*(\.\w{2,3})+$/.test(value),
    [value]
  );

  let options = [
    { id: 1, email: 'fake@email.com' },
    { id: 2, email: 'anotherfake@email.com' },
    { id: 3, email: 'bob@email.com' },
    { id: 4, email: 'joe@email.com' },
    { id: 5, email: 'yourEmail@email.com' },
    { id: 6, email: 'valid@email.com' },
    { id: 7, email: 'spam@email.com' },
    { id: 8, email: 'newsletter@email.com' },
    { id: 9, email: 'subscribe@email.com' }
  ];

  return (
    <SearchAutocomplete
      width="size-3000"
      label="Search Email Addresses"
      validationState={isValid ? 'valid' : 'invalid'}
      defaultItems={options}
      inputValue={value}
      onInputChange={setValue}
    >
      {(item) => <Item>{item.email}</Item>}
    </SearchAutocomplete>
  );
}
function Example() {
  let [value, setValue] = React.useState('me@email.com');
  let isValid = React.useMemo(
    () =>
      /^\w+([\.-]?\w+)*@\w+([\.-]?\w+)*(\.\w{2,3})+$/.test(
        value
      ),
    [value]
  );

  let options = [
    { id: 1, email: 'fake@email.com' },
    { id: 2, email: 'anotherfake@email.com' },
    { id: 3, email: 'bob@email.com' },
    { id: 4, email: 'joe@email.com' },
    { id: 5, email: 'yourEmail@email.com' },
    { id: 6, email: 'valid@email.com' },
    { id: 7, email: 'spam@email.com' },
    { id: 8, email: 'newsletter@email.com' },
    { id: 9, email: 'subscribe@email.com' }
  ];

  return (
    <SearchAutocomplete
      width="size-3000"
      label="Search Email Addresses"
      validationState={isValid ? 'valid' : 'invalid'}
      defaultItems={options}
      inputValue={value}
      onInputChange={setValue}
    >
      {(item) => <Item>{item.email}</Item>}
    </SearchAutocomplete>
  );
}
function Example() {
  let [value, setValue] =
    React.useState(
      'me@email.com'
    );
  let isValid = React
    .useMemo(
      () =>
        /^\w+([\.-]?\w+)*@\w+([\.-]?\w+)*(\.\w{2,3})+$/
          .test(value),
      [value]
    );

  let options = [
    {
      id: 1,
      email:
        'fake@email.com'
    },
    {
      id: 2,
      email:
        'anotherfake@email.com'
    },
    {
      id: 3,
      email:
        'bob@email.com'
    },
    {
      id: 4,
      email:
        'joe@email.com'
    },
    {
      id: 5,
      email:
        'yourEmail@email.com'
    },
    {
      id: 6,
      email:
        'valid@email.com'
    },
    {
      id: 7,
      email:
        'spam@email.com'
    },
    {
      id: 8,
      email:
        'newsletter@email.com'
    },
    {
      id: 9,
      email:
        'subscribe@email.com'
    }
  ];

  return (
    <SearchAutocomplete
      width="size-3000"
      label="Search Email Addresses"
      validationState={isValid
        ? 'valid'
        : 'invalid'}
      defaultItems={options}
      inputValue={value}
      onInputChange={setValue}
    >
      {(item) => (
        <Item>
          {item.email}
        </Item>
      )}
    </SearchAutocomplete>
  );
}

Custom Filtering#


By default, SearchAutocomplete uses a string "contains" filtering strategy when deciding what items to display in the dropdown menu. This filtering strategy can be overwritten by filtering the list of items yourself and passing the filtered list to the SearchAutocomplete via the items prop.

The example below uses a string "startsWith" filter function obtained from the useFilter hook to display items that start with the SearchAutocomplete's current input value only. By using the menuTrigger returned by onOpenChange, it also handles displaying the entire option list regardless of the current filter value when the SearchAutocomplete menu is opened via the trigger button or arrow keys. menuTrigger tells you if the menu was opened manually by the user ("manual"), by focusing the SearchAutocomplete ("focus"), or by changes in the input field ("input"), allowing you to make updates to other controlled aspects of your SearchAutocomplete accordingly.

function Example() {
  let options = [
    { id: 1, email: 'fake@email.com' },
    { id: 2, email: 'anotherfake@email.com' },
    { id: 3, email: 'bob@email.com' },
    { id: 4, email: 'joe@email.com' },
    { id: 5, email: 'yourEmail@email.com' },
    { id: 6, email: 'valid@email.com' },
    { id: 7, email: 'spam@email.com' },
    { id: 8, email: 'newsletter@email.com' },
    { id: 9, email: 'subscribe@email.com' }
  ];

  let [showAll, setShowAll] = React.useState(false);
  let [filterValue, setFilterValue] = React.useState('');
  let { startsWith } = useFilter({ sensitivity: 'base' });
  let filteredItems = React.useMemo(
    () => options.filter((item) => startsWith(item.email, filterValue)),
    [options, filterValue]
  );

  return (
    <SearchAutocomplete
      onOpenChange={(isOpen, menuTrigger) => {
        // Show all items if menu is opened manually
        // i.e. by the arrow keys or trigger button
        if (menuTrigger === 'manual' && isOpen) {
          setShowAll(true);
        }
      }}
      width="size-3000"
      label="Search Email Addresses"
      items={showAll ? options : filteredItems}
      inputValue={filterValue}
      onInputChange={(value) => {
        setShowAll(false);
        setFilterValue(value);
      }}
    >
      {(item) => <Item>{item.email}</Item>}
    </SearchAutocomplete>
  );
}
function Example() {
  let options = [
    { id: 1, email: 'fake@email.com' },
    { id: 2, email: 'anotherfake@email.com' },
    { id: 3, email: 'bob@email.com' },
    { id: 4, email: 'joe@email.com' },
    { id: 5, email: 'yourEmail@email.com' },
    { id: 6, email: 'valid@email.com' },
    { id: 7, email: 'spam@email.com' },
    { id: 8, email: 'newsletter@email.com' },
    { id: 9, email: 'subscribe@email.com' }
  ];

  let [showAll, setShowAll] = React.useState(false);
  let [filterValue, setFilterValue] = React.useState('');
  let { startsWith } = useFilter({ sensitivity: 'base' });
  let filteredItems = React.useMemo(
    () =>
      options.filter((item) =>
        startsWith(item.email, filterValue)
      ),
    [options, filterValue]
  );

  return (
    <SearchAutocomplete
      onOpenChange={(isOpen, menuTrigger) => {
        // Show all items if menu is opened manually
        // i.e. by the arrow keys or trigger button
        if (menuTrigger === 'manual' && isOpen) {
          setShowAll(true);
        }
      }}
      width="size-3000"
      label="Search Email Addresses"
      items={showAll ? options : filteredItems}
      inputValue={filterValue}
      onInputChange={(value) => {
        setShowAll(false);
        setFilterValue(value);
      }}
    >
      {(item) => <Item>{item.email}</Item>}
    </SearchAutocomplete>
  );
}
function Example() {
  let options = [
    {
      id: 1,
      email:
        'fake@email.com'
    },
    {
      id: 2,
      email:
        'anotherfake@email.com'
    },
    {
      id: 3,
      email:
        'bob@email.com'
    },
    {
      id: 4,
      email:
        'joe@email.com'
    },
    {
      id: 5,
      email:
        'yourEmail@email.com'
    },
    {
      id: 6,
      email:
        'valid@email.com'
    },
    {
      id: 7,
      email:
        'spam@email.com'
    },
    {
      id: 8,
      email:
        'newsletter@email.com'
    },
    {
      id: 9,
      email:
        'subscribe@email.com'
    }
  ];

  let [
    showAll,
    setShowAll
  ] = React.useState(
    false
  );
  let [
    filterValue,
    setFilterValue
  ] = React.useState('');
  let { startsWith } =
    useFilter({
      sensitivity: 'base'
    });
  let filteredItems =
    React.useMemo(
      () =>
        options.filter(
          (item) =>
            startsWith(
              item.email,
              filterValue
            )
        ),
      [
        options,
        filterValue
      ]
    );

  return (
    <SearchAutocomplete
      onOpenChange={(
        isOpen,
        menuTrigger
      ) => {
        // Show all items if menu is opened manually
        // i.e. by the arrow keys or trigger button
        if (
          menuTrigger ===
            'manual' &&
          isOpen
        ) {
          setShowAll(
            true
          );
        }
      }}
      width="size-3000"
      label="Search Email Addresses"
      items={showAll
        ? options
        : filteredItems}
      inputValue={filterValue}
      onInputChange={(
        value
      ) => {
        setShowAll(
          false
        );
        setFilterValue(
          value
        );
      }}
    >
      {(item) => (
        <Item>
          {item.email}
        </Item>
      )}
    </SearchAutocomplete>
  );
}

Trigger options#


By default, the SearchAutocomplete's menu is opened when the user types into the input field ("input"). There are two other supported modes: one where the menu opens when the SearchAutocomplete is focused ("focus") and the other where the menu only opens when the user clicks or taps on the SearchAutocomplete's field button ("manual"). These can be set by providing "focus" or "manual" to the menuTrigger prop. Guidelines on when to use a specific mode can be found here. Note that the mobile SearchAutocomplete experience requires the end user to press the SearchAutocomplete button to open the tray regardless of the menuTrigger setting.

<SearchAutocomplete label="Favorite Animal" menuTrigger="focus">
  <Item>Red Panda</Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>
<SearchAutocomplete
  label="Favorite Animal"
  menuTrigger="focus"
>
  <Item>Red Panda</Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>
<SearchAutocomplete
  label="Favorite Animal"
  menuTrigger="focus"
>
  <Item>Red Panda</Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>
<SearchAutocomplete label="Favorite Animal" menuTrigger="manual">
  <Item>Red Panda</Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>
<SearchAutocomplete
  label="Favorite Animal"
  menuTrigger="manual"
>
  <Item>Red Panda</Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>
<SearchAutocomplete
  label="Favorite Animal"
  menuTrigger="manual"
>
  <Item>Red Panda</Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>

Props#


NameTypeDefaultDescription
childrenCollectionChildren<object>The contents of the collection.
menuTriggerMenuTriggerAction'input'The interaction required to display the SearchAutocomplete menu. Note that this prop has no effect on the mobile SearchAutocomplete experience.
isQuietbooleanWhether the SearchAutocomplete should be displayed with a quiet style.
direction'bottom''top''bottom'Direction the menu will render relative to the SearchAutocomplete.
loadingStateLoadingStateThe current loading state of the SearchAutocomplete. Determines whether or not the progress circle should be shown.
shouldFlipbooleantrueWhether the menu should automatically flip direction when space is limited.
defaultItemsIterable<object>The list of SearchAutocomplete items (uncontrolled).
itemsIterable<object>The list of SearchAutocomplete items (controlled).
inputValuestringThe value of the SearchAutocomplete input (controlled).
defaultInputValuestringThe default value of the SearchAutocomplete input (uncontrolled).
disabledKeysIterable<Key>The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.
isDisabledbooleanWhether the input is disabled.
isReadOnlybooleanWhether the input can be selected but not changed by the user.
validationStateValidationStateWhether the input should display its "valid" or "invalid" visual styling.
isRequiredboolean

Whether user input is required on the input before form submission. Often paired with the necessityIndicator prop to add a visual indicator to the input.

descriptionReactNodeA description for the field. Provides a hint such as specific requirements for what to choose.
errorMessageReactNodeAn error message for the field.
autoFocusbooleanWhether the element should receive focus on render.
valuestringThe current value (controlled).
defaultValuestringThe default value (uncontrolled).
labelReactNodeThe content to display as the label.
labelPositionLabelPosition'top'The label's overall position relative to the element it is labeling.
labelAlignAlignment'start'The label's horizontal alignment relative to the element it is labeling.
necessityIndicatorNecessityIndicator'icon'Whether the required state should be shown as an icon or text.
Events
NameTypeDefaultDescription
onLoadMore() => void
onOpenChange( (isOpen: boolean, , menuTrigger?: MenuTriggerAction )) => voidMethod that is called when the open state of the menu changes. Returns the new open state and the action that caused the opening of the menu.
onInputChange( (value: string )) => voidHandler that is called when the SearchAutocomplete input value changes.
onSubmit( (value: string, , key: Keynull )) => void
onClear() => voidHandler that is called when the clear button is pressed.
onFocus( (e: FocusEvent )) => voidHandler that is called when the element receives focus.
onBlur( (e: FocusEvent )) => voidHandler that is called when the element loses focus.
onFocusChange( (isFocused: boolean )) => voidHandler that is called when the element's focus status changes.
onKeyDown( (e: KeyboardEvent )) => voidHandler that is called when a key is pressed.
onKeyUp( (e: KeyboardEvent )) => voidHandler that is called when a key is released.
onChange( (value: object )) => voidHandler that is called when the value changes.
Layout
NameTypeDefaultDescription
flexResponsive<stringnumberboolean>When used in a flex layout, specifies how the element will grow or shrink to fit the space available. See MDN.
flexGrowResponsive<number>When used in a flex layout, specifies how the element will grow to fit the space available. See MDN.
flexShrinkResponsive<number>When used in a flex layout, specifies how the element will shrink to fit the space available. See MDN.
flexBasisResponsive<numberstring>When used in a flex layout, specifies the initial main size of the element. See MDN.
alignSelfResponsive<'auto''normal''start''end''center''flex-start''flex-end''self-start''self-end''stretch'>Overrides the alignItems property of a flex or grid container. See MDN.
justifySelfResponsive<'auto''normal''start''end''flex-start''flex-end''self-start''self-end''center''left''right''stretch'>Specifies how the element is justified inside a flex or grid container. See MDN.
orderResponsive<number>The layout order for the element within a flex or grid container. See MDN.
gridAreaResponsive<string>When used in a grid layout, specifies the named grid area that the element should be placed in within the grid. See MDN.
gridColumnResponsive<string>When used in a grid layout, specifies the column the element should be placed in within the grid. See MDN.
gridRowResponsive<string>When used in a grid layout, specifies the row the element should be placed in within the grid. See MDN.
gridColumnStartResponsive<string>When used in a grid layout, specifies the starting column to span within the grid. See MDN.
gridColumnEndResponsive<string>When used in a grid layout, specifies the ending column to span within the grid. See MDN.
gridRowStartResponsive<string>When used in a grid layout, specifies the starting row to span within the grid. See MDN.
gridRowEndResponsive<string>When used in a grid layout, specifies the ending row to span within the grid. See MDN.
Spacing
NameTypeDefaultDescription
marginResponsive<DimensionValue>The margin for all four sides of the element. See MDN.
marginTopResponsive<DimensionValue>The margin for the top side of the element. See MDN.
marginBottomResponsive<DimensionValue>The margin for the bottom side of the element. See MDN.
marginStartResponsive<DimensionValue>The margin for the logical start side of the element, depending on layout direction. See MDN.
marginEndResponsive<DimensionValue>The margin for the logical end side of an element, depending on layout direction. See MDN.
marginXResponsive<DimensionValue>The margin for both the left and right sides of the element. See MDN.
marginYResponsive<DimensionValue>The margin for both the top and bottom sides of the element. See MDN.
Sizing
NameTypeDefaultDescription
widthResponsive<DimensionValue>The width of the element. See MDN.
minWidthResponsive<DimensionValue>The minimum width of the element. See MDN.
maxWidthResponsive<DimensionValue>The maximum width of the element. See MDN.
heightResponsive<DimensionValue>The height of the element. See MDN.
minHeightResponsive<DimensionValue>The minimum height of the element. See MDN.
maxHeightResponsive<DimensionValue>The maximum height of the element. See MDN.
Positioning
NameTypeDefaultDescription
positionResponsive<'static''relative''absolute''fixed''sticky'>Specifies how the element is positioned. See MDN.
topResponsive<DimensionValue>The top position for the element. See MDN.
bottomResponsive<DimensionValue>The bottom position for the element. See MDN.
leftResponsive<DimensionValue>The left position for the element. See MDN. Consider using start instead for RTL support.
rightResponsive<DimensionValue>The right position for the element. See MDN. Consider using start instead for RTL support.
startResponsive<DimensionValue>The logical start position for the element, depending on layout direction. See MDN.
endResponsive<DimensionValue>The logical end position for the element, depending on layout direction. See MDN.
zIndexResponsive<number>The stacking order for the element. See MDN.
isHiddenResponsive<boolean>Hides the element.
Advanced
NameTypeDefaultDescription
UNSAFE_classNamestringSets the CSS className for the element. Only use as a last resort. Use style props instead.
UNSAFE_styleCSSPropertiesSets inline style for the element. Only use as a last resort. Use style props instead.

Visual options#


Label alignment and position#

By default, the label is positioned above the SearchAutocomplete. The labelPosition prop can be used to position the label to the side. The labelAlign prop can be used to align the label as "start" or "end". For left-to-right (LTR) languages, "start" refers to the left most edge of the SearchAutocomplete and "end" refers to the right most edge. For right-to-left (RTL) languages, this is flipped.

<SearchAutocomplete
  label="Favorite Animal"
  labelPosition="side"
  labelAlign="end"
>
  <Item>Red Panda</Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>
<SearchAutocomplete
  label="Favorite Animal"
  labelPosition="side"
  labelAlign="end"
>
  <Item>Red Panda</Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>
<SearchAutocomplete
  label="Favorite Animal"
  labelPosition="side"
  labelAlign="end"
>
  <Item>Red Panda</Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>

Quiet#

<SearchAutocomplete label="Favorite Animal" isQuiet>
  <Item>Red Panda</Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>
<SearchAutocomplete label="Favorite Animal" isQuiet>
  <Item>Red Panda</Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>
<SearchAutocomplete
  label="Favorite Animal"
  isQuiet
>
  <Item>
    Red Panda
  </Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>

Disabled#

<SearchAutocomplete label="Favorite Animal" isDisabled>
  <Item>Red Panda</Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>
<SearchAutocomplete label="Favorite Animal" isDisabled>
  <Item>Red Panda</Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>
<SearchAutocomplete
  label="Favorite Animal"
  isDisabled
>
  <Item>
    Red Panda
  </Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>

Read only#

<SearchAutocomplete label="Search Animals" isReadOnly>
  <Item>Red Panda</Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>
<SearchAutocomplete label="Search Animals" isReadOnly>
  <Item>Red Panda</Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>
<SearchAutocomplete
  label="Search Animals"
  isReadOnly
>
  <Item>
    Red Panda
  </Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>

Custom widths#

<SearchAutocomplete label="Favorite Animal" width="size-6000" maxWidth="100%">
  <Item>Red Panda</Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>
<SearchAutocomplete
  label="Favorite Animal"
  width="size-6000"
  maxWidth="100%"
>
  <Item>Red Panda</Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>
<SearchAutocomplete
  label="Favorite Animal"
  width="size-6000"
  maxWidth="100%"
>
  <Item>Red Panda</Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>
<SearchAutocomplete label="Favorite Animal" direction="top">
  <Item>Red Panda</Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>
<SearchAutocomplete label="Favorite Animal" direction="top">
  <Item>Red Panda</Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>
<SearchAutocomplete
  label="Favorite Animal"
  direction="top"
>
  <Item>
    Red Panda
  </Item>
  <Item>Cat</Item>
  <Item>Dog</Item>
  <Item>Aardvark</Item>
  <Item>Kangaroo</Item>
  <Item>Snake</Item>
</SearchAutocomplete>