Autocomplete

Import

import { Autocomplete } from '@contentful/f36-components';
// or
import { Autocomplete } from '@contentful/f36-autocomplete';

Examples

Basic usage

The Autocomplete requires 3 props to work:

• items: It’s an array containing the items that will be shown as selectable options when the user types something in the TextInput.
• onInputValueChange: This function will be called every time the user types something in the input. The component will pass the item, which the filter method is currently iterating over, and the inputValue prop of the TextInput component.
• onSelectItem: This function is called when the user selects one of the options of the list. The component will pass the selected item as an argument to the function.

An Autocomplete with a list of spaces will look like this:

Hide code
function AutocompleteBasicUsageExample() {
  const spaces = [
    'Travel Blog',
    'Finnance Blog',
    'Fitness App',
    'News Website',
    'eCommerce Catalogue',
    'Photo Gallery',
  ];

  // This `useState` is going to store the selected "space" so we can show it in the UI
  const [selectedSpace, setSelectedSpace] = React.useState();
  const [filteredItems, setFilteredItems] = React.useState(spaces);

  // We filter the "spaces" array by the inputValue
  // we use 'toLowerCase()' to make the search case insensitive
  const handleInputValueChange = (value) => {
    const newFilteredItems = spaces.filter((item) =>
      item.toLowerCase().includes(value.toLowerCase()),
    );
    setFilteredItems(newFilteredItems);
  };

  // This function will be called once the user selects an item in the list of options
  const handleSelectItem = (item) => {
    setSelectedSpace(item);
  };

  return (
    <Stack flexDirection="column" alignItems="start">
      <Autocomplete
        items={filteredItems}
        onInputValueChange={handleInputValueChange}
        onSelectItem={handleSelectItem}
      />

      <Paragraph>
        Selected space: <b>{selectedSpace}</b>
      </Paragraph>
    </Stack>
  );
}
Open in Playground

Using objects as items

We showed how to create an Autocomplete with an array of string but it’s also possible to use other types of data as items. A very common way of using the Autocomplete is with objects and for that, with a few changes to the previous example this can be done:

Hide code
function AutocompleteWithObjectsExample() {
  const spaces = [
    { name: 'Travel Blog', type: 'Community' },
    { name: 'Finnance Blog', type: 'Community' },
    { name: 'Fitness App', type: 'Medium' },
    { name: 'News Website', type: 'Medium' },
    { name: 'eCommerce Catalogue', type: 'Large' },
    { name: 'Photo Gallery', type: 'Large' },
  ];

  const [selectedSpace, setSelectedSpace] = React.useState({ name: '' });
  const [filteredItems, setFilteredItems] = React.useState(spaces);

  const handleInputValueChange = (value) => {
    // This time, we tell the component to compare the property "name" to the inputValue
    const newFilteredItems = spaces.filter((item) =>
      item.name.toLowerCase().includes(value.toLowerCase()),
    );
    setFilteredItems(newFilteredItems);
  };

  const handleSelectItem = (item) => {
    setSelectedSpace(item);
  };

  return (
    <Stack flexDirection="column" alignItems="start">
      <Autocomplete
        items={filteredItems}
        onInputValueChange={handleInputValueChange}
        onSelectItem={handleSelectItem}
        // This prop is the function that will tell the component
        // how to extract a string that will be used as inputValue
        itemToString={(item) => item.name}
        // This prop is the function that will tell the component
        // how to render each item in the options list
        // In this example the first item will render "Travel Blog (Community)"
        renderItem={(item) => `${item.name} (${item.type})`}
      />

      <Paragraph>
        Selected fruit: <b>{selectedSpace.name}</b>
      </Paragraph>
    </Stack>
  );
}
Open in Playground

Both itemToString and renderItem are necessary when passing objects as items and they both will receive an "item" as an argument.

If you are using Typescript, you can tell the Autocomplete what is the type of your items to make these functions strongly typed. You can do that by writing the component like this <Autocomplete<ItemType> {...props}/>

Highlighting an item with getStringMatch

A common use case for Autocomplete components is to highlight in each suggestion what is typed in the input. Using the previous example, if a user types "fi" we want to show a list of suggestions where only "fi" is bold. This is possible by using the renderItem prop and the getStringMatch utility function:

Hide code
function AutocompleteHighlightingExample() {
  const spaces = [
    { name: 'Travel Blog', type: 'Community' },
    { name: 'Finnance Blog', type: 'Community' },
    { name: 'Fitness App', type: 'Medium' },
    { name: 'News Website', type: 'Medium' },
    { name: 'eCommerce Catalogue', type: 'Large' },
    { name: 'Photo Gallery', type: 'Large' },
  ];

  const [selectedSpace, setSelectedSpace] = React.useState({ name: '' });
  const [filteredItems, setFilteredItems] = React.useState(spaces);

  return (
    <Stack flexDirection="column" alignItems="start">
      <Autocomplete
        items={filteredItems}
        onInputValueChange={(value) => {
          const newFilteredItems = spaces.filter((item) =>
            item.name.toLowerCase().includes(value.toLowerCase()),
          );
          setFilteredItems(newFilteredItems);
        }}
        onSelectItem={(item) => setSelectedSpace(item)}
        itemToString={(item) => item.name}
        // Two arguments are provided to the `renderItem` prop: the item and the inputValue
        renderItem={(item, inputValue) => {
          // we pass `item.name` and the inputValue to getStringMatch
          // and it will return an object
          // for our example, for the "Travel Blog" item
          // this will return { before: 'T' , match: 'rav', after: 'el Blog' }
          const { before, match, after } = getStringMatch(
            item.name,
            inputValue,
          );

          // Finally, we return a ReactNode
          return (
            <>
              {before}
              <b>{match}</b>
              {after} ({item.type})
            </>
          );
        }}
      />

      <Paragraph>
        Selected fruit: <b>{selectedSpace.name}</b>
      </Paragraph>
    </Stack>
  );
}
Open in Playground

Selecting multiple items

It is also possible to use the Autocomplete as multiselect. To improve the user experience, you can keep the dropdown open after selection by setting the "closeAfterSelect" property to false.

Hide code
function AutocompleteMultiSelectionExample() {
  const spaces = [
    { name: 'Travel Blog', type: 'Community' },
    { name: 'Finnance Blog', type: 'Community' },
    { name: 'Fitness App', type: 'Medium' },
    { name: 'News Website', type: 'Medium' },
    { name: 'eCommerce Catalogue', type: 'Large' },
    { name: 'Photo Gallery', type: 'Large' },
  ];

  // The state now stores an array of selected spaces, not just a string
  const [selectedFruits, setSelectedFruits] = React.useState([]);
  const [filteredItems, setFilteredItems] = React.useState(spaces);

  const handleInputValueChange = (value) => {
    const newFilteredItems = spaces.filter((item) =>
      item.name.toLowerCase().includes(value.toLowerCase()),
    );
    setFilteredItems(newFilteredItems);
  };

  const handleSelectItem = (item) => {
    // Every time an item is selected, the component will add the name of the fruit to the selectedFruits array
    setSelectedFruits((prevState) => [...prevState, item.name]);
  };

  return (
    <Stack flexDirection="column" alignItems="start">
      <Autocomplete
        items={filteredItems}
        onInputValueChange={handleInputValueChange}
        onSelectItem={handleSelectItem}
        itemToString={(item) => item.name}
        renderItem={(item) => item.name}
        // When `textOnAfterSelect` is `"clear"`, it will clean the TextInput after an option is selected
        textOnAfterSelect="clear"
        closeAfterSelect={false}
      />

      <span>
        <Paragraph>Selected spaces:</Paragraph>
        <ul>
          {selectedFruits.map((fruit, index) => (
            <li key={index}>{fruit}</li>
          ))}
        </ul>
      </span>
    </Stack>
  );
}
Open in Playground

Using grouped objects as items

As an extension of "Use objects as items" section, you are also able to use a nested object to group your entries. The most important part of making this work is the shape of the grouped object. The options themselves work exactly as in the object example and require the itemToString and renderItem functions. Besides the correct shape of the object the Autocomplete component needs to receive the prop isGrouped

Hide code
function AutocompleteWithGroupedItems() {
  const spaces = [
    {
      groupTitle: 'Blogs',
      options: [
        { name: 'Travel Blog', type: 'Community' },
        { name: 'Finnance Blog', type: 'Community' },
      ],
    },
    {
      groupTitle: 'Others',
      options: [
        { name: 'Fitness App', type: 'Medium' },
        { name: 'News Website', type: 'Medium' },
        { name: 'eCommerce Catalogue', type: 'Large' },
        { name: 'Photo Gallery', type: 'Large' },
      ],
    },
  ];

  const [selectedItem, setSelectedItem] = React.useState({ name: '' });
  const [filteredItems, setFilteredItems] = React.useState(spaces);

  const handleInputValueChange = (value) => {
    // we have to make sure to filter each of the groups based on the items shape.
    // be aware this is just a basic example and you might need to apply a more advanced filter algorithm
    const newFilteredItems = spaces.map((group) => {
      return {
        ...group,
        options: group.options.filter((item) =>
          item.name.toLowerCase().includes(value.toLowerCase()),
        ),
      };
    });
    setFilteredItems(newFilteredItems);
  };

  const handleSelectItem = (item) => {
    setSelectedItem(item);
  };

  return (
    <Stack flexDirection="column" alignItems="start">
      <Autocomplete
        items={filteredItems}
        // this is the important prop that tells the component to deal with grouped options
        isGrouped
        onInputValueChange={handleInputValueChange}
        onSelectItem={handleSelectItem}
        itemToString={(item) => `${item.name} (${item.type})`}
        renderItem={(item) => `${item.name} (${item.type})`}
      />

      <Paragraph>
        Selected item from shopping list: {selectedItem.name}
      </Paragraph>
    </Stack>
  );
}
Open in Playground

Fully controlled selection from outside

In order to use proper form validation you need to be able to control the actual input field from the autocomplete, because the search query value is not the actual selection. This is done via the selectedItem property.

Hide code
function ControlledAutocomplete() {
  const spaces = [
    { name: 'Travel Blog', type: 'Community' },
    { name: 'Finnance Blog', type: 'Community' },
    { name: 'Fitness App', type: 'Medium' },
    { name: 'News Website', type: 'Medium' },
    { name: 'eCommerce Catalogue', type: 'Large' },
    { name: 'Photo Gallery', type: 'Large' },
  ];

  const [selectedSpace, setSelectedSpace] = React.useState({ name: '' });
  const [filteredItems, setFilteredItems] = React.useState(spaces);

  const handleInputValueChange = (value) => {
    // This time, we tell the component to compare the property "name" to the inputValue
    const newFilteredItems = spaces.filter((item) =>
      item.name.toLowerCase().includes(value.toLowerCase()),
    );
    setFilteredItems(newFilteredItems);
  };

  const handleSelectItem = (item) => {
    setSelectedSpace(item);
  };

  return (
    <Stack flexDirection="column" alignItems="start">
      <Autocomplete
        items={filteredItems}
        onInputValueChange={handleInputValueChange}
        onSelectItem={handleSelectItem}
        // handing selectedItem over as property make the autocomplete a controlled input
        selectedItem={selectedSpace}
        // This prop is the function that will tell the component
        // how to extract a string that will be used as inputValue
        itemToString={(item) => item.name}
        // This prop is the function that will tell the component
        // how to render each item in the options list
        // In this example the first item will render "Travel Blog (Community)"
        renderItem={(item) => `${item.name} (${item.type})`}
      />

      <Paragraph>
        Selected Space: <b>{selectedSpace.name}</b>
        <Button onClick={() => setSelectedSpace({ name: '' })}>
          clear selection
        </Button>
      </Paragraph>
    </Stack>
  );
}
Open in Playground

Error validation with FormControl

Hide code
function AutocompleteWithErrorValidationExample() {
  const spaces = [
    'Travel Blog',
    'Finnance Blog',
    'Fitness App',
    'News Website',
    'eCommerce Catalogue',
    'Photo Gallery',
  ];

  const [selectedFruit, setSelectedFruit] = React.useState();
  const [filteredItems, setFilteredItems] = React.useState(spaces);
  const [isInvalid, setIsInvalid] = React.useState(false);

  const handleInputValueChange = (value) => {
    const newFilteredItems = spaces.filter((item) =>
      item.toLowerCase().includes(value.toLowerCase()),
    );
    setFilteredItems(newFilteredItems);
  };

  const handleSelectItem = (item) => {
    setSelectedFruit(item);
  };

  return (
    <Stack flexDirection="column" alignItems="start">
      <FormControl isInvalid={isInvalid}>
        <FormControl.Label>Space:</FormControl.Label>

        <Autocomplete
          items={filteredItems}
          onInputValueChange={handleInputValueChange}
          onSelectItem={handleSelectItem}
        />

        {isInvalid && (
          <FormControl.ValidationMessage>Error</FormControl.ValidationMessage>
        )}
      </FormControl>

      <Button onClick={() => setIsInvalid((prevState) => !prevState)}>
        Toggle error message
      </Button>

      <Paragraph>
        Selected space: <b>{selectedFruit}</b>
      </Paragraph>
    </Stack>
  );
}
Open in Playground

Fetching async data

Hide code
function AutocompleteFetchingAsyncDataExample() {
  const spaces = React.useMemo(
    () => [
      'Travel Blog',
      'Finnance Blog',
      'Fitness App',
      'News Website',
      'eCommerce Catalogue',
      'Photo Gallery',
    ],
    [],
  );

  const [selectedFruit, setSelectedFruit] = React.useState();

  const [isLoading, setIsLoading] = React.useState(false);
  const [inputValue, setInputValue] = React.useState('');
  const [items, setItems] = React.useState([]);

  React.useEffect(() => {
    setIsLoading(true);

    // We will use a timeout to simulate async data
    // this function will filter our options after 800ms
    const fetchSpaces = setTimeout(() => {
      const filteredSpaces = spaces.filter((item) =>
        item.toLowerCase().includes(inputValue.toLowerCase()),
      );
      setItems(filteredSpaces);
      setIsLoading(false);
    }, 800);

    return () => clearTimeout(fetchSpaces);
  }, [inputValue, spaces]);

  // fetching data on each input value change
  // NOTE: Consider using throttle/debounce here for better performance
  const handleInputValueChange = (value) => {
    setInputValue(value);
  };

  const handleSelectItem = (item) => {
    setSelectedFruit(item);
  };

  return (
    <Stack flexDirection="column" alignItems="start">
      <Autocomplete
        items={items}
        onInputValueChange={handleInputValueChange}
        onSelectItem={handleSelectItem}
        isLoading={isLoading}
        defaultValue={inputValue}
      />

      <Paragraph>
        Selected fruit: <b>{selectedFruit}</b>
      </Paragraph>
    </Stack>
  );
}
Open in Playground

Custom icon

Pass a custom icon to the text input, example: to indicate a search input

Hide code
function AutocompleteBasicUsageExample() {
  const spaces = [
    'Travel Blog',
    'Finnance Blog',
    'Fitness App',
    'News Website',
    'eCommerce Catalogue',
    'Photo Gallery',
  ];

  // This `useState` is going to store the selected "space" so we can show it in the UI
  const [selectedSpace, setSelectedSpace] = React.useState();
  const [filteredItems, setFilteredItems] = React.useState(spaces);

  // We filter the "spaces" array by the inputValue
  // we use 'toLowerCase()' to make the search case insensitive
  const handleInputValueChange = (value) => {
    const newFilteredItems = spaces.filter((item) =>
      item.toLowerCase().includes(value.toLowerCase()),
    );
    setFilteredItems(newFilteredItems);
  };

  // This function will be called once the user selects an item in the list of options
  const handleSelectItem = (item) => {
    setSelectedSpace(item);
  };

  return (
    <Stack flexDirection="column" alignItems="start">
      <Autocomplete
        items={filteredItems}
        icon={<SearchIcon variant="muted" />}
        onInputValueChange={handleInputValueChange}
        onSelectItem={handleSelectItem}
      />

      <Paragraph>
        Selected space: <b>{selectedSpace}</b>
      </Paragraph>
    </Stack>
  );
}
Open in Playground

Content guidelines

• Autocomplete label should be short, contain 1 to 3 words
• Label should be written in a sentence case (the first word capitalized, the rest lowercase)

Accessibility

• dismisses the dropdown when selecting with the enter key