Autocomplete

function Demo () {
    const [value, setValue] = React.useState("");
    const options = ["Pizza", "Pie", "Ice-cream"];

    const handleChange = (args) => setValue(args.value);

    return (
      <View width="300px" maxWidth="100%">
        <Autocomplete placeholder="Pick your food" onChange={handleChange} value={value}>
          {options.map((option) => {
            if (!option.toLowerCase().includes(value.toLowerCase())) return;
            if (option === value) return;

            return (
              <Autocomplete.Item key={option} value={option}>
                {option}
              </Autocomplete.Item>
            );
          })}
        </Autocomplete>
      </View>
    );

}

Autocomplete suggests the values provided to it as children. The list is shown once user focuses on the field and gets hidden once they select a value or there is no content rendered.

Here is the most basic example, which always renders the same passed items and autocompletes the field on selecting one of them:

function DemoBasic() {
  const [value, setValue] = React.useState("");
  const options = ["Pizza", "Pie", "Ice-cream"];

  const handleChange = (args) => setValue(args.value);

  return (
    <Autocomplete
      name="fruit"
      placeholder="Pick your food"
      value={value}
      onChange={handleChange}
    >
      {options.map((option) => (
        <Autocomplete.Item key={option} value={option}>
          {option}
        </Autocomplete.Item>
      ))}
    </Autocomplete>
  );
}

Autocomplete supports all properties TextField supports, including its variants, sizes and slots. Since Autocomplete is a form element, name is a required property to make it work.

Autocomplete gives you full control over the items rendering and filtering. That means you can remove any items from rendering based on the user input or control async data loading.

function DemoFiltering() {
  const [value, setValue] = React.useState("");
  const options = ["Pizza", "Pie", "Ice-cream"];

  const handleChange = (args) => setValue(args.value);

  return (
    <Autocomplete
      name="fruit"
      placeholder="Pick your food"
      value={value}
      onChange={handleChange}
    >
      {options.map((option) => {
        if (!option.toLowerCase().includes(value.toLowerCase())) return;

        return (
          <Autocomplete.Item key={option} value={option}>
            {option}
          </Autocomplete.Item>
        );
      })}
    </Autocomplete>
  );
}

You can fully customize the composition of the dropdown content. Autocomplete.Item supports the same properties as MenuItem, making the layout of each item very flexible, as well as allowing to implement custom wrappers around the items. Use onItemSelect when you want to render anything in the field not on every value change, but only when an item is selected.

function DemoComposition() {
  const [value, setValue] = React.useState("");
  const [selectedItem, setSelectedItem] = React.useState("");
  const options = [
    {
      title: "Paul Farell",
      role: "Designer",
      photo: "/img/examples/avatar-3.png",
    },
    {
      title: "Esther Naomi",
      role: "Developer",
      photo: "/img/examples/avatar-2.png",
    },
    {
      title: "Whitney Raynolds",
      role: "Developer",
      photo: "/img/examples/avatar-1.png",
    },
  ];

  const handleChange = (args) => setValue(args.value);
  const handleItemSelect = (args) => {
    setSelectedItem(args.value);
    setValue("");
  };

  return (
    <Autocomplete
      name="people"
      placeholder="Pick assignee"
      value={value}
      onChange={handleChange}
      onItemSelect={handleItemSelect}
      startSlot={selectedItem && <Badge>{selectedItem}</Badge>}
    >
      {options.map((option) => {
        const valueMatch = value.toLowerCase();
        const optionValue = option.title.toLowerCase();

        if (!optionValue.includes(valueMatch) || valueMatch === optionValue)
          return;

        return (
          <Autocomplete.Item
            key={option.title}
            value={option.title}
            startSlot={<Avatar src={option.photo} size={7} />}
            endSlot={<Badge>{option.role}</Badge>}
          >
            {option.title}
          </Autocomplete.Item>
        );
      })}
    </Autocomplete>
  );
}

Same as when using native inputs in React, Autocomplete can be used as a controlled or uncontrolled component. By default, Autocomplete is uncontrolled and lets you define its default value using the defaultValue property. In this case, all change events are handled automatically. This approach is helpful when you're pre-filling a form from a data source, but you don't need to control the further behavior of the input.

If you need to control the state of the field manually, you can use the value property. That will give you complete control of the component value and will stop handling the value automatically. You will have to update the state using the onChange handler and will be able to add custom logic before that happens.