ComboBox

View source on GitHub

ComboBox is the combination of a Textfield and an associated Dropdown that allows the user to filter a list when selecting an option. ComboBox allows users to type the full option, type part of the option and narrow the results, or select an option from the list.

Props

Name	Type	Default
`accessibilityClearButtonLabel` Required	`string`	-
	Label to describe the clear button's purpose.
`id` Required	`string`	-
	Unique id to identify each ComboBox. Used for accessibility purposes.
`label` Required	`string`	-
	Provide a label to identify the ComboBox field.
`noResultText` Required	`string`	-
	The text shown when the input value returns no matches
`options` Required	`Array<{\| label: string, value: string, subtext: string \|}>`	-
	The data for each selection option. See subtext variant to learn more
`disabled`	`boolean`	`false`
	When disabled, ComboBox looks inactive and cannot be interacted with. If tags are passed, they will appear disabled as well and cannot be removed. See tags variant to learn more.
`errorMessage`	`string`	-
	Provide feedback when an error on selection occurs. See error message variant.
`helperText`	`string`	-
	Provides additional information about how to select a ComboBox option.
`inputValue`	`string`	-
	The user input in ComboBox for controlled components. See controlled ComboBox variant to learn more.
`labelDisplay`	`"visible"\|"hidden"`	`"visible"`
	Whether the label should be visible or not. If `hidden`, the label is still available for screen reader users, but does not appear visually. See the label visibility variant for more info.
`onBlur`	`({ event: SyntheticFocusEvent<HTMLInputElement> \| SyntheticEvent<HTMLInputElement> , value: string }) => void`	-
	Callback when you focus outside the component
`onChange`	`({ event: SyntheticInputEvent<>, value: string }) => void`	-
	Callback when user types into the control input field
`onClear`	`() => void`	-
	Callback when user clicks on clear button
`onFocus`	`({ event: SyntheticFocusEvent<>, value: string }) => void`	-
	Callback when you focus on the component
`onKeyDown`	`({ event: SyntheticKeyboardEvent<HTMLTextAreaElement>, value: string }) => void`	-
	Callback for key stroke events. See tags variant to learn more.
`onSelect`	`({ event: SyntheticInputEvent<>, value: string }) => void`	-
	Callback when an item is selected
`placeholder`	`string`	-
	Specify a short description that suggests the expected input for the field
`ref`	`React.Ref<"input">`	-
	Forward the ref to the underlying component container element. See focus management variant to learn more
`selectedOption`	`{\| label: string, value: string, subtext: string \|}`	-
	The selected option in ComboBox for controlled components. See controlled ComboBox variant to learn more.
`size`	`"md" \| "lg"`	`"md"`
	Defines the height of ComboBox: md: 40px, lg: 48px. Width is defined by parent component.
`tags`	`Array<Element<typeof Tag>>`	-
	List of tags to display in the component. See tags variant to learn more.

Usage guidelines

When to Use

Presenting users with a long list of options (typically 10 or more) that can be filtered by typing in the text field.

When Not to Use

For shorter lists of items where filtering is not needed, typically under 10 items.

Best practices

Use ComboBox to allow the user to edit or copy the textfield input values to select and/or narrow down from a given list of options.

Don't

Use ComboBox for a simple list of items. Use SelectList instead for the added native mobile functionality.

Accessibility

Labels

ComboBox requires both label and accessibilityClearButtonLabel. By default, the label is visible above TextField. However, if the form items are labelled by content elsewhere on the page, or a more complex label is needed, the labelDisplay prop can be used to visually hide the label. In this case, it is still available to screen reader users, but will not appear visually on the screen.

In the example below, the "Discover this week's top searched trends across all categories" text is acting as a heading, so instead of repeating another label, we visually hide the label. When a user focuses on the ComboBox, a screen reader will announce "Choose a category to display top search trends, Select category".

Discover this week's top searched trends across all categories

Wanna learn how trends work? Read additional information

function ComboBoxExample(props) {
  const CATEGORIES = [
    'All Categories',
    'Food and drinks',
    'Beauty',
    'Home decor',
    'Fashion',
    'Travel',
    'Art',
    'Quotes',
    'Entertainment',
    'Entertainment',
    'DIY and crafts',
    'Health',
    'Wedding',
    'Event planning',
    'Gardening',
    'Parenting',
    'Vehicles',
    'Design',
    'Sport',
    'Electronics',
    'Animals',
    'Finance',
    'Architecture',
  ];

  const options = CATEGORIES.map((category, index) => ({
    label: category,
    value: 'value'+index ,
  }));

  const [errorMessage, setErrorMessage] = React.useState();

  const handleOnBlur = ({ value }) => {
    if (value !== '' && !CATEGORIES.includes(value))
      setErrorMessage('Please, select a valid option');
  };

  const resetErrorMessage = () => (errorMessage ? setErrorMessage() : () => {});

  return (
    <Flex
      direction="column"
      gap={2}
    >
      <Heading size="md">Discover this week's top searched trends across all categories</Heading>
      <Text inline> Wanna learn how trends work? Read
        <Text weight="bold" inline>
          <Link accessibilityLabel="Learn how trends on Pinterest work" target="blank" inline href="https://business.pinterest.com/content/pinterest-predicts/">
            additional information
          </Link>
        </Text>
      </Text>
      <ComboBox
        accessibilityClearButtonLabel="Clear category value"
        errorMessage={errorMessage}
        id="displayLabel"
        label="Choose a category to display top search trends"
        labelDisplay="hidden"
        noResultText="No results for your selection"
        onBlur={handleOnBlur}
        onChange={resetErrorMessage}
        onClear={resetErrorMessage}
        options={options}
        placeholder="Select category"
      />
    </Flex>
  );
}

function ComboBoxExample(props) {
  const CATEGORIES = [
    'All Categories',
    'Food and drinks',
    'Beauty',
    'Home decor',
    'Fashion',
    'Travel',
    'Art',
    'Quotes',
    'Entertainment',
    'Entertainment',
    'DIY and crafts',
    'Health',
    'Wedding',
    'Event planning',
    'Gardening',
    'Parenting',
    'Vehicles',
    'Design',
    'Sport',
    'Electronics',
    'Animals',
    'Finance',
    'Architecture',
  ];
  const options = CATEGORIES.map((category, index) => ({
    label: category,
    value: 'value'+index ,
  }));
  const [errorMessage, setErrorMessage] = React.useState();
  const handleOnBlur = ({ value }) => {
    if (value !== '' && !CATEGORIES.includes(value))
      setErrorMessage('Please, select a valid option');
  };
  const resetErrorMessage = () => (errorMessage ? setErrorMessage() : () => {});
  return (
    <Flex
      direction="column"
      gap={2}
    >
      <Heading size="md">Discover this week's top searched trends across all categories</Heading>
      <Text inline> Wanna learn how trends work? Read
        <Text weight="bold" inline>
          <Link accessibilityLabel="Learn how trends on Pinterest work" target="blank" inline href="https://business.pinterest.com/content/pinterest-predicts/">
            additional information
          </Link>
        </Text>
      </Text>
      <ComboBox
        accessibilityClearButtonLabel="Clear category value"
        errorMessage={errorMessage}
        id="displayLabel"
        label="Choose a category to display top search trends"
        labelDisplay="hidden"
        noResultText="No results for your selection"
        onBlur={handleOnBlur}
        onChange={resetErrorMessage}
        onClear={resetErrorMessage}
        options={options}
        placeholder="Select category"
      />
    </Flex>
  );
}

Keyboard interaction

Hitting Enter or Space key on the ComboBox's trigger opens the options list
Once an item is selected, hitting Enter or Space on the clear button clears the selection and returns focus to the input textfield
Escape key closes the options list, while moving focus back on the ComboBox's trigger
Arrow keys are used to navigate items within the options list
Enter key selects an item within the options list
Tab or Shift + Tab close the options list and move focus accordingly

Localization

Be sure to localize the helperText, errorMessage, noResultText, label, placeholder, and accessibilityClearButtonLabel props. options and value should be localized for those cases that can be translated. Note that localization can lengthen text by 20 to 30 percent.

function ComboBoxExample(props) {
  const PRONOUNS = [
    'ell@ / l@ / -@',
    'ella / la / le / -a',
    'elle / le / -e',
    'ellx / lx / -x',
    'él / lo / le / -o',
  ];

  const options = PRONOUNS.map((pronoun, index) => ({ label: pronoun, value: 'value'+index }));

  const [errorMessage, setErrorMessage] = React.useState();

  const handleOnBlur = ({ value }) => {
    if (value !== "" && !PRONOUNS.includes(value)) setErrorMessage('Por favor, selecciona una opción válida');
  };

  const resetErrorMessage = () => (errorMessage ? setErrorMessage() : () => {});

  return (
    <Box width={400}>
      <ComboBox
        accessibilityClearButtonLabel="Remueve la lista de pronombres seleccionados"
        errorMessage={errorMessage}
        helperText="Elige hasta 2 grupos de pronombres para que aparezcan en tu perfil y otras personas sepan cómo referirse a ti. Puedes editarlos o eliminarlos en cualquier momento."
        id="localization"
        label="Pronombres"
        noResultText="No se encontró ninguna coincidencia"
        onBlur={handleOnBlur}
        onChange={resetErrorMessage}
        onClear={resetErrorMessage}
        options={options}
        placeholder="Añade tus pronombres"
      />
    </Box>

  );
}

function ComboBoxExample(props) {
  const PRONOUNS = [
    'ell@ / l@ / -@',
    'ella / la / le / -a',
    'elle / le / -e',
    'ellx / lx / -x',
    'él / lo / le / -o',
  ];
  const options = PRONOUNS.map((pronoun, index) => ({ label: pronoun, value: 'value'+index }));
  const [errorMessage, setErrorMessage] = React.useState();
  const handleOnBlur = ({ value }) => {
    if (value !== "" && !PRONOUNS.includes(value)) setErrorMessage('Por favor, selecciona una opción válida');
  };
  const resetErrorMessage = () => (errorMessage ? setErrorMessage() : () => {});
  return (
    <Box width={400}>
      <ComboBox
        accessibilityClearButtonLabel="Remueve la lista de pronombres seleccionados"
        errorMessage={errorMessage}
        helperText="Elige hasta 2 grupos de pronombres para que aparezcan en tu perfil y otras personas sepan cómo referirse a ti. Puedes editarlos o eliminarlos en cualquier momento."
        id="localization"
        label="Pronombres"
        noResultText="No se encontró ninguna coincidencia"
        onBlur={handleOnBlur}
        onChange={resetErrorMessage}
        onClear={resetErrorMessage}
        options={options}
        placeholder="Añade tus pronombres"
      />
    </Box>
  );
}

Variants

Controlled vs Uncontrolled

ComboBox can be used as a controlled or an uncontrolled component. An uncontrolled ComboBox stores its own state internally and updates it based on the user input. On the other side, a controlled ComboBox's state is managed by a parent component. The parent component's state passes new values through props to the controlled component which notifies changes through event callbacks.

Uncontrolled ComboBox

An uncontrolled ComboBox should be used for basic cases where no default value or tags are required. Don't pass inputValue or selectedOptions props to keep the component uncontrolled. By passing inputValue to ComboBox, the component fully manages its internal state: any value different from null and undefined makes Combobox controlled.

function ComboBoxExample(props) {
  const PRONOUNS = [
    'ey / em',
    'he / him',
    'ne / nem',
    'she / her',
    'they / them',
    've / ver',
    'xe / xem',
    'xie / xem',
    'zie / zem',
  ];

  const options = PRONOUNS.map((pronoun, index) => ({ label: pronoun, value: 'value'+index }));

  const [errorMessage, setErrorMessage] = React.useState();

  const handleOnBlur = ({ value }) => {
    if (value !== "" && !PRONOUNS.includes(value)) setErrorMessage('Please, select a valid option');
  };

  const resetErrorMessage = () => (errorMessage ? setErrorMessage() : () => {});

  return (
    <Box width={400}>
      <ComboBox
        accessibilityClearButtonLabel="Clear the current value"
        errorMessage={errorMessage}
        helperText="Choose your pronouns to appear on your profile so others know how to refer to you. You can edit or remove these any time."
        id="uncontrolled"
        label="Pronouns"
        noResultText="No results for your selection"
        onBlur={handleOnBlur}
        onChange={resetErrorMessage}
        onClear={resetErrorMessage}
        options={options}
        placeholder="Add your pronouns"
      />
    </Box>
  );
}

function ComboBoxExample(props) {
  const PRONOUNS = [
    'ey / em',
    'he / him',
    'ne / nem',
    'she / her',
    'they / them',
    've / ver',
    'xe / xem',
    'xie / xem',
    'zie / zem',
  ];
  const options = PRONOUNS.map((pronoun, index) => ({ label: pronoun, value: 'value'+index }));
  const [errorMessage, setErrorMessage] = React.useState();
  const handleOnBlur = ({ value }) => {
    if (value !== "" && !PRONOUNS.includes(value)) setErrorMessage('Please, select a valid option');
  };
  const resetErrorMessage = () => (errorMessage ? setErrorMessage() : () => {});
  return (
    <Box width={400}>
      <ComboBox
        accessibilityClearButtonLabel="Clear the current value"
        errorMessage={errorMessage}
        helperText="Choose your pronouns to appear on your profile so others know how to refer to you. You can edit or remove these any time."
        id="uncontrolled"
        label="Pronouns"
        noResultText="No results for your selection"
        onBlur={handleOnBlur}
        onChange={resetErrorMessage}
        onClear={resetErrorMessage}
        options={options}
        placeholder="Add your pronouns"
      />
    </Box>
  );
}

Controlled ComboBox

A controlled ComboBox is required if a selected value is set, as shown in the first example. In the second example, values are set programatically. Controlled Comboboxes with tags are also controlled components. A controlled ComboBox requires three value props: options, inputValue, and selectedOptions. ComboBox is notified of changes via the onChange, onSelect, onBlur, onFocus, onKeyDown, and onClear props. All values displayed by ComboBox at any time are controlled externally. To clear inputValue, set the value to an empty string inputValue = "", null or undefined values turn ComboBox into an uncontrolled component.

Estimated tax to be collected in CA - California will be calculated at checkout

function ComboBoxExample(props) {
  const US_STATES = [
    'AK - Alaska',
    'AL - Alabama',
    'AR - Arkansas',
    'AS - American Samoa',
    'AZ - Arizona',
    'CA - California',
    'CO - Colorado',
    'CT - Connecticut',
    'DC - District of Columbia',
    'DE - Delaware',
    'FL - Florida',
    'GA - Georgia',
    'GU - Guam',
    'HI - Hawaii',
    'IA - Iowa',
    'ID - Idaho',
    'IL - Illinois',
    'IN - Indiana',
    'KS - Kansas',
    'KY - Kentucky',
    'LA - Louisiana',
    'MA - Massachusetts',
    'MD - Maryland',
    'ME - Maine',
    'MI - Michigan',
    'MN - Minnesota',
    'MO - Missouri',
    'MS - Mississippi',
    'MT - Montana',
    'NC - North Carolina',
    'ND - North Dakota',
    'NE - Nebraska',
    'NH - New Hampshire',
    'NJ - New Jersey',
    'NM - New Mexico',
    'NV - Nevada',
    'NY - New York',
    'OH - Ohio',
    'OK - Oklahoma',
    'OR - Oregon',
    'PA - Pennsylvania',
    'PR - Puerto Rico',
    'RI - Rhode Island',
    'SC - South Carolina',
    'SD - South Dakota',
    'TN - Tennessee',
    'TX - Texas',
    'UT - Utah',
    'VA - Virginia',
    'VI - Virgin Islands',
    'VT - Vermont',
    'WA - Washington',
    'WI - Wisconsin',
    'WV - West Virginia',
    'WY - Wyoming',
  ];

  const usStatesOptions = US_STATES.map((pronoun, index) => ({ label: pronoun, value: 'value'+index }));

  const [suggestedOptions, setSuggestedOptions] = React.useState(usStatesOptions);
  const [inputValue, setInputValue] = React.useState(usStatesOptions[5].label);
  const [selected, setSelected] = React.useState(usStatesOptions[5]);

  const handleOnChange = ({ value }) => {
    setSelected();
    if (value) {
      setInputValue(value);
      const filteredOptions = usStatesOptions.filter((item) =>
        item.label.toLowerCase().includes(value.toLowerCase()),
      );
      setSuggestedOptions(filteredOptions);
    } else {
      setInputValue(value);
      setSuggestedOptions(usStatesOptions);
    }
  };

  const handleSelect = ({ item }) => {
    setInputValue(item.label);
    setSuggestedOptions(usStatesOptions);
    setSelected(item);
  };

  return (
    <Flex direction="column" gap={10} width="50%">
      <ComboBox
        accessibilityClearButtonLabel="Clear the current value"
        label="State"
        id="controlled"
        inputValue={inputValue}
        noResultText="No results for your selection"
        options={suggestedOptions}
        onBlur={() => {
          if (!selected) setInputValue("");
          setSuggestedOptions(usStatesOptions);
        }}
        onClear={() => {
          setInputValue("")
          setSelected();
          setSuggestedOptions(usStatesOptions);
        }}
        selectedOption={selected}
        placeholder="Select a US state"
        onChange={handleOnChange}
        onSelect={handleSelect}
      />
      { selected && selected.label
        ? <Text>Estimated tax to be collected in { (selected && selected.label) } will be calculated at checkout</Text>
        : null
      }
    </Flex>
  );
}

function ComboBoxExample(props) {
  const US_STATES = [
    'AK - Alaska',
    'AL - Alabama',
    'AR - Arkansas',
    'AS - American Samoa',
    'AZ - Arizona',
    'CA - California',
    'CO - Colorado',
    'CT - Connecticut',
    'DC - District of Columbia',
    'DE - Delaware',
    'FL - Florida',
    'GA - Georgia',
    'GU - Guam',
    'HI - Hawaii',
    'IA - Iowa',
    'ID - Idaho',
    'IL - Illinois',
    'IN - Indiana',
    'KS - Kansas',
    'KY - Kentucky',
    'LA - Louisiana',
    'MA - Massachusetts',
    'MD - Maryland',
    'ME - Maine',
    'MI - Michigan',
    'MN - Minnesota',
    'MO - Missouri',
    'MS - Mississippi',
    'MT - Montana',
    'NC - North Carolina',
    'ND - North Dakota',
    'NE - Nebraska',
    'NH - New Hampshire',
    'NJ - New Jersey',
    'NM - New Mexico',
    'NV - Nevada',
    'NY - New York',
    'OH - Ohio',
    'OK - Oklahoma',
    'OR - Oregon',
    'PA - Pennsylvania',
    'PR - Puerto Rico',
    'RI - Rhode Island',
    'SC - South Carolina',
    'SD - South Dakota',
    'TN - Tennessee',
    'TX - Texas',
    'UT - Utah',
    'VA - Virginia',
    'VI - Virgin Islands',
    'VT - Vermont',
    'WA - Washington',
    'WI - Wisconsin',
    'WV - West Virginia',
    'WY - Wyoming',
  ];
  const usStatesOptions = US_STATES.map((pronoun, index) => ({ label: pronoun, value: 'value'+index }));
  const [suggestedOptions, setSuggestedOptions] = React.useState(usStatesOptions);
  const [inputValue, setInputValue] = React.useState(usStatesOptions[5].label);
  const [selected, setSelected] = React.useState(usStatesOptions[5]);
  const handleOnChange = ({ value }) => {
    setSelected();
    if (value) {
      setInputValue(value);
      const filteredOptions = usStatesOptions.filter((item) =>
        item.label.toLowerCase().includes(value.toLowerCase()),
      );
      setSuggestedOptions(filteredOptions);
    } else {
      setInputValue(value);
      setSuggestedOptions(usStatesOptions);
    }
  };
  const handleSelect = ({ item }) => {
    setInputValue(item.label);
    setSuggestedOptions(usStatesOptions);
    setSelected(item);
  };
  return (
    <Flex direction="column" gap={10} width="50%">
      <ComboBox
        accessibilityClearButtonLabel="Clear the current value"
        label="State"
        id="controlled"
        inputValue={inputValue}
        noResultText="No results for your selection"
        options={suggestedOptions}
        onBlur={() => {
          if (!selected) setInputValue("");
          setSuggestedOptions(usStatesOptions);
        }}
        onClear={() => {
          setInputValue("")
          setSelected();
          setSuggestedOptions(usStatesOptions);
        }}
        selectedOption={selected}
        placeholder="Select a US state"
        onChange={handleOnChange}
        onSelect={handleSelect}
      />
      { selected && selected.label
        ? <Text>Estimated tax to be collected in { (selected && selected.label) } will be calculated at checkout</Text>
        : null
      }
    </Flex>
  );
}

function ComboBoxExample(props) {

  const CATEGORIES = { "BEAUTY": [
    'Beauty tips',
    'DIY beauty',
    'Wedding beauty',
    'Vegan beauty products',
    'Beauty photography',
    'Beauty quotes',
    'Beauty illustration',
    'Beauty salon',
    'Beauty blender',
   ].map((pronoun, index) => ({ label: pronoun, value: 'value'+index })),
   "DIY": [
    'DIY Projects',
    'DIY Art',
    'DIY Home decor',
    'DIY Furniture',
    'DIY Gifts',
    'DIY Wall decor',
    'DIY Clothes',
    'DIY Christmas decorations',
    'DIY Christmas gifts',
    'DIY Wall art'].map((pronoun, index) => ({ label: pronoun, value: 'value'+index }))
  };

  const [currentCategory, setCurrentCategory] = React.useState("BEAUTY");

  const [suggestedOptions, setSuggestedOptions] = React.useState(CATEGORIES[currentCategory]);

  const [inputValue, setInputValue] = React.useState("");

  const [selectedOption, setSelectedOption] = React.useState();

  const resetOptions = () => {
    setSuggestedOptions(CATEGORIES[currentCategory]);
  }

  const handleOnChange = ({ value }) => {
    setSelectedOption()
    if (value) {
      setInputValue(value);
      const filteredOptions = CATEGORIES[currentCategory].filter((item) =>
        item.label.toLowerCase().includes(value.toLowerCase()),
      );
      setSuggestedOptions(filteredOptions);
    } else {
      setInputValue(value);
      resetOptions();
    }
  };

  const handleSelect = ({ item }) => {
    setInputValue(item.label);
    setSelectedOption(item);
    resetOptions();
  };

  const handleOnBlur = () => {
    if (!selectedOption) setInputValue("");
    resetOptions();
  }

  const handleOnClear = () => {
    setInputValue("");
    setSelectedOption()
    resetOptions();
  }

  return (
    <Flex direction="column" gap={10}>
      <Button
        onClick={() => {
          const nextCategory = currentCategory === 'BEAUTY' ? 'DIY' : 'BEAUTY';
          setCurrentCategory(nextCategory)
          setSuggestedOptions(CATEGORIES[nextCategory])
          setInputValue("")
        }}
        text={"Change options to " + (currentCategory === "BEAUTY" ? "DIY" : "BEAUTY") + " category"}
        inline
        />
      <ComboBox
        accessibilityClearButtonLabel="Clear the current value"
        id="programaticallySet"
        inputValue={inputValue}
        noResultText="No results for your selection"
        options={suggestedOptions}
        label="Pin category"
        size="lg"
        onBlur={handleOnBlur}
        onClear={handleOnClear}
        placeholder="Select a category"
        onChange={handleOnChange}
        onSelect={handleSelect}
        selectedOption={selectedOption}
      />
    </Flex>
  );
}

function ComboBoxExample(props) {
  const CATEGORIES = { "BEAUTY": [
    'Beauty tips',
    'DIY beauty',
    'Wedding beauty',
    'Vegan beauty products',
    'Beauty photography',
    'Beauty quotes',
    'Beauty illustration',
    'Beauty salon',
    'Beauty blender',
   ].map((pronoun, index) => ({ label: pronoun, value: 'value'+index })),
   "DIY": [
    'DIY Projects',
    'DIY Art',
    'DIY Home decor',
    'DIY Furniture',
    'DIY Gifts',
    'DIY Wall decor',
    'DIY Clothes',
    'DIY Christmas decorations',
    'DIY Christmas gifts',
    'DIY Wall art'].map((pronoun, index) => ({ label: pronoun, value: 'value'+index }))
  };
  const [currentCategory, setCurrentCategory] = React.useState("BEAUTY");
  const [suggestedOptions, setSuggestedOptions] = React.useState(CATEGORIES[currentCategory]);
  const [inputValue, setInputValue] = React.useState("");
  const [selectedOption, setSelectedOption] = React.useState();
  const resetOptions = () => {
    setSuggestedOptions(CATEGORIES[currentCategory]);
  }
  const handleOnChange = ({ value }) => {
    setSelectedOption()
    if (value) {
      setInputValue(value);
      const filteredOptions = CATEGORIES[currentCategory].filter((item) =>
        item.label.toLowerCase().includes(value.toLowerCase()),
      );
      setSuggestedOptions(filteredOptions);
    } else {
      setInputValue(value);
      resetOptions();
    }
  };
  const handleSelect = ({ item }) => {
    setInputValue(item.label);
    setSelectedOption(item);
    resetOptions();
  };
  const handleOnBlur = () => {
    if (!selectedOption) setInputValue("");
    resetOptions();
  }
  const handleOnClear = () => {
    setInputValue("");
    setSelectedOption()
    resetOptions();
  }
  return (
    <Flex direction="column" gap={10}>
      <Button
        onClick={() => {
          const nextCategory = currentCategory === 'BEAUTY' ? 'DIY' : 'BEAUTY';
          setCurrentCategory(nextCategory)
          setSuggestedOptions(CATEGORIES[nextCategory])
          setInputValue("")
        }}
        text={"Change options to " + (currentCategory === "BEAUTY" ? "DIY" : "BEAUTY") + " category"}
        inline
        />
      <ComboBox
        accessibilityClearButtonLabel="Clear the current value"
        id="programaticallySet"
        inputValue={inputValue}
        noResultText="No results for your selection"
        options={suggestedOptions}
        label="Pin category"
        size="lg"
        onBlur={handleOnBlur}
        onClear={handleOnClear}
        placeholder="Select a category"
        onChange={handleOnChange}
        onSelect={handleSelect}
        selectedOption={selectedOption}
      />
    </Flex>
  );
}

Ref

To control focus or position and anchor components to ComboBox, use ref as shown in the examples below.

Focus management

function ComboBoxExample() {
  const ref = React.useRef();

  return (
    <Flex gap={4}>
      <ComboBox
        accessibilityClearButtonLabel="Clear the current values"
        label="Select your favorite shape"
        id="favoriteShape"
        noResultText="No results for your selection"
        options={[{ label:'square', value:'1'}, { label:'circle', value:'2'}]}
        onSelect={() => ref.current.focus()}
        placeholder="Select a shape"
      />
      <ComboBox
        accessibilityClearButtonLabel="Clear the current values"
        label="Select your favorite color"
        id="favoriteColor"
        noResultText="No results for your selection"
        options={[{ label:'red', value:'1'}, { label:'blue', value:'2'}, { label:'green', value:'3'}, { label:'yellow', value:'4'}]}
        placeholder="Select a color"
        ref={ref}
      />
    </Flex>
  );
}

function ComboBoxExample() {
  const ref = React.useRef();
  return (
    <Flex gap={4}>
      <ComboBox
        accessibilityClearButtonLabel="Clear the current values"
        label="Select your favorite shape"
        id="favoriteShape"
        noResultText="No results for your selection"
        options={[{ label:'square', value:'1'}, { label:'circle', value:'2'}]}
        onSelect={() => ref.current.focus()}
        placeholder="Select a shape"
      />
      <ComboBox
        accessibilityClearButtonLabel="Clear the current values"
        label="Select your favorite color"
        id="favoriteColor"
        noResultText="No results for your selection"
        options={[{ label:'red', value:'1'}, { label:'blue', value:'2'}, { label:'green', value:'3'}, { label:'yellow', value:'4'}]}
        placeholder="Select a color"
        ref={ref}
      />
    </Flex>
  );
}

With subtext

Display subtext under each selection option

function ComboBoxExample(props) {
  const [item, setItem] = React.useState('');
  const [selected, setSelected] = React.useState(null);

  const options = Array(20).fill(0).map((item, index) => ({
    label: "Label-" + (index + 1),
    value: "Value-" + (index + 1),
    subtext: "Subtext-" + (index + 1),
  }));

  const handleOnChange = ({ value }) => setItem(value);

  const handleSelect = ({ item }) => setSelected(item);

  const label = "Selected Item: " + (selected && selected.value || '');

  return (
    <ComboBox
      accessibilityClearButtonLabel="Clear the current value"
      label="Choose a value"
      id="subtext"
      noResultText="No results for your selection"
      options={options}
      placeholder="Select a value"
      onChange={handleOnChange}
      onSelect={handleSelect}
    />
  );
}

function ComboBoxExample(props) {
  const [item, setItem] = React.useState('');
  const [selected, setSelected] = React.useState(null);
  const options = Array(20).fill(0).map((item, index) => ({
    label: "Label-" + (index + 1),
    value: "Value-" + (index + 1),
    subtext: "Subtext-" + (index + 1),
  }));
  const handleOnChange = ({ value }) => setItem(value);
  const handleSelect = ({ item }) => setSelected(item);
  const label = "Selected Item: " + (selected && selected.value || '');
  return (
    <ComboBox
      accessibilityClearButtonLabel="Clear the current value"
      label="Choose a value"
      id="subtext"
      noResultText="No results for your selection"
      options={options}
      placeholder="Select a value"
      onChange={handleOnChange}
      onSelect={handleSelect}
    />
  );
}

Error message

function ComboBoxExample(props) {
  return (
    <Box width={400}>
      <ComboBox
        accessibilityClearButtonLabel="Clear the current value"
        errorMessage="Please select a valid category"
        id="error"
        label="Category"
        noResultText="No results for your selection"
        options={[]}
      />
    </Box>
  );
}

function ComboBoxExample(props) {
  return (
    <Box width={400}>
      <ComboBox
        accessibilityClearButtonLabel="Clear the current value"
        errorMessage="Please select a valid category"
        id="error"
        label="Category"
        noResultText="No results for your selection"
        options={[]}
      />
    </Box>
  );
}

SelectList
If users need to select from a short, simple list (without needing sections, subtext details, or the ability to filter the list), use SelectList.

Dropdown
Dropdown is an element constructed using Popover as its container. Use Dropdown to display a list of actions or options in a Popover.

Fieldset
Use Fieldset to group related form items.

Edit page on GitHub