# Combobox
> Combobox combines a text input with a list of options that users are able to choose from.

## Import

```js
import { Combobox } from '@gemini-suite/vera-react';

// you may also access Combobox context via hook:
// import { useComboboxContext } from '@gemini-suite/vera-react';
```

Combobox is a compound component that consists of multiple parts:

- `Combobox.Root`: The wrapper that contains all the parts of a combobox and provides context for its children.
- `Combobox.TextInput`: The input that allows users to filter the list of items or type the value they want. It is also the trigger for combobox listbox.
- `Combobox.Content`: A wrapper for the content to be rendered when the combobox menu is open. It positions itself by aligning over `Combobox.TextInput`.
- `Combobox.Clear`: The button that clears the value of combobox.
- `Combobox.Item`: A container for combobox's item of choice.
- `Combobox.ItemText`: A wrapper around textual part of `Combobox.Item`.
- `Combobox.ItemIndicator`: A visual cue in form of an icon that is displayed when the item is selected.
- `Combobox.NoValueFound`: The wrapper for providing content to display when there are no matching item(s) in the list.

## Examples

### Basic

`Combobox` displays a list of items for the user to pick from. By default `Combobox.TextInput` acts as a typeahead search that matches relevant item and reflects the currently selected value.
Printable characters will expand the items dropdown and the first item that matches the query will be visually highlighted (based on the order of the items).

<Callout variant="tip">

Provide `placeholder` prop in `Combobox.TextInput` when the combobox input does not have an initial value.

</Callout>

```jsx
<Combobox.Root>
  <Combobox.TextInput aria-label="Fruit" placeholder="Pick a fruit…" />
  <Combobox.Content>
    <Combobox.Item value="apple">{'Apple'}</Combobox.Item>
    <Combobox.Item value="banana">{'Banana'}</Combobox.Item>
    <Combobox.Item value="grape">{'Grape'}</Combobox.Item>
    <Combobox.Item value="orange">{'Orange'}</Combobox.Item>
    <Combobox.Item value="strawberry">{'Strawberry'}</Combobox.Item>
    <Combobox.Item value="mango">{'Mango'}</Combobox.Item>
  </Combobox.Content>
</Combobox.Root>
```

### With default value

An initial, uncontrolled value can be provided using the `defaultValue` prop.
The item corresponding with the value will be highlighted on the list.

```jsx
<Combobox.Root defaultValue="banana">
  <Combobox.TextInput aria-label="Fruit" placeholder="Pick a fruit…" />
  <Combobox.Content>
    <Combobox.Item value="apple">{'Apple'}</Combobox.Item>
    <Combobox.Item value="banana">{'Banana'}</Combobox.Item>
    <Combobox.Item value="grape">{'Grape'}</Combobox.Item>
    <Combobox.Item value="orange">{'Orange'}</Combobox.Item>
    <Combobox.Item value="strawberry">{'Strawberry'}</Combobox.Item>
    <Combobox.Item value="mango">{'Mango'}</Combobox.Item>
  </Combobox.Content>
</Combobox.Root>
```

### Controlled value

You can easily make the `Combobox` controlled, by passing your own state to `value` prop. `onValueChange` handler is called when
the selected value changes, allowing you to sync state.

```jsx
() => {
  const [value, setValue] = React.useState('avocado');

  return (
    <Flex flow="column">
      <Combobox.Root value={value} onValueChange={setValue}>
        <Combobox.TextInput
          aria-label="Fruit"
          placeholder="Search favorite fruit…"
        />
        <Combobox.Content>
          <Combobox.Item value="apple">{'Apple'}</Combobox.Item>
          <Combobox.Item value="avocado">{'Avocado'}</Combobox.Item>
          <Combobox.Item value="banana">{'Banana'}</Combobox.Item>
          <Combobox.Item value="kiwi">{'Kiwi'}</Combobox.Item>
          <Combobox.Item value="mango">{'Mango'}</Combobox.Item>
          <Combobox.Item value="orange">{'Orange'}</Combobox.Item>
          <Combobox.Item value="grapes">{'Grapes'}</Combobox.Item>
          <Combobox.Item value="strawberry">{'Strawberry'}</Combobox.Item>
          <Combobox.Item value="pineapple">{'Pineapple'}</Combobox.Item>
        </Combobox.Content>
      </Combobox.Root>
      <Box>{value ? `Your favorite fruit is: ${value}` : null}</Box>
    </Flex>
  );
};
```

### Controlled text value

In addition to controlling `value` of the combobox you can also control value of the `Combobox.TextInput` with `textValue` prop and `onTextValueChange` handler.

```jsx
() => {
  const [value, setValue] = React.useState('');
  const [textValue, setTextValue] = React.useState('');

  return (
    <Flex flow="column">
      <Flex flow="column" gap="spacingXs">
        <Box>{`Selected value: ${value}`}</Box>
        <Box>{`Input value: ${textValue}`}</Box>
      </Flex>
      <Combobox.Root
        value={value}
        onValueChange={setValue}
        textValue={textValue}
        onTextValueChange={setTextValue}
      >
        <Combobox.TextInput
          aria-label="Fruit"
          placeholder="Select favorite fruit…"
        />
        <Combobox.Content>
          <Combobox.Item value="apple">{'Apple'}</Combobox.Item>
          <Combobox.Item value="avocado">{'Avocado'}</Combobox.Item>
          <Combobox.Item value="banana">{'Banana'}</Combobox.Item>
          <Combobox.Item value="kiwi">{'Kiwi'}</Combobox.Item>
          <Combobox.Item value="mango">{'Mango'}</Combobox.Item>
          <Combobox.Item value="orange">{'Orange'}</Combobox.Item>
          <Combobox.Item value="grapes">{'Grapes'}</Combobox.Item>
          <Combobox.Item value="strawberry">{'Strawberry'}</Combobox.Item>
          <Combobox.Item value="pineapple">{'Pineapple'}</Combobox.Item>
        </Combobox.Content>
      </Combobox.Root>
    </Flex>
  );
};
```

### Autocomplete mode

Set `autocomplete` prop to `list`, to activate autocomplete behavior known as list autocomplete.
If the user types one or more characters in the `Combobox.TextInput`, only items that are relevant for the provided query are displayed.
As the user types more text into the input field, the displayed list of matching items is updated.

<Callout variant="tip">

Autocomplete mode may be useful when users need to select from a large set of possible options. For more limited option sets, consider default behavior which does not filter and only moves focus to the closest matching item.

</Callout>

```jsx
() => {
  const itemsToFilter = [
    { label: 'Banana', value: 'banana' },
    { label: 'Blueberry', value: 'blueberry' },
    { label: 'Wild Blueberry', value: 'wild-blueberry' },
    { label: 'Bubble Gum', value: 'bubble-gum' },
    { label: 'Chocolate', value: 'chocolate' },
    { label: 'Coconut', value: 'coconut' },
    { label: 'Coffee', value: 'coffee' },
    { label: 'Cookie Dough', value: 'cookie-dough' },
    { label: 'Cotton Candy', value: 'cotton-candy' },
    { label: 'Mango', value: 'mango' },
    { label: 'Matcha', value: 'matcha' },
    { label: 'Mint', value: 'mint' },
    { label: 'Oreo', value: 'oreo' },
    { label: 'Peanut Butter', value: 'peanut-butter' },
    { label: 'Pistachio', value: 'pistachio' },
    { label: 'Pumpkin', value: 'pumpkin' },
    { label: 'Salted Caramel', value: 'salted-caramel' },
    { label: 'Strawberry', value: 'strawberry' },
    { label: 'Vanilla', value: 'vanilla' }
  ];

  return (
    <Combobox.Root autocomplete="list">
      <Combobox.TextInput
        aria-label="Food"
        placeholder="Search favorite food…"
        endElement={<Combobox.Clear label="Clear" />}
      />
      <Combobox.Content>
        {itemsToFilter.map(({ value, label }) => (
          <Combobox.Item key={value} value={value}>
            {label}
          </Combobox.Item>
        ))}
        <Combobox.NoValueFound>{'No options found.'}</Combobox.NoValueFound>
      </Combobox.Content>
    </Combobox.Root>
  );
};
```

### Autocomplete filtering

`Combobox` provides 2 built-in filtering mechanisms based on substring matches with locale sensitive matching support.

- `startsWith` (default) shows items that starts with the input value.
- `contains` shows items that contains the input value.

Use `defaultFilter` property to select the filtering strategy that suits your specific use case.

<Callout variant="tip">

A custom filter function can also be passed to the `defaultFilter` prop, it receives an item value and the input value as parameters, and should return a `boolean`.

</Callout>

```jsx
() => {
  const itemsToFilter = [
    { label: 'Banana', value: 'banana' },
    { label: 'Blueberry', value: 'blueberry' },
    { label: 'Wild Blueberry', value: 'wild-blueberry' },
    { label: 'Bubble Gum', value: 'bubble-gum' },
    { label: 'Chocolate', value: 'chocolate' },
    { label: 'Coconut', value: 'coconut' },
    { label: 'Coffee', value: 'coffee' },
    { label: 'Cookie Dough', value: 'cookie-dough' },
    { label: 'Cotton Candy', value: 'cotton-candy' },
    { label: 'Mango', value: 'mango' },
    { label: 'Matcha', value: 'matcha' },
    { label: 'Mint', value: 'mint' },
    { label: 'Oreo', value: 'oreo' },
    { label: 'Peanut Butter', value: 'peanut-butter' },
    { label: 'Pistachio', value: 'pistachio' },
    { label: 'Pumpkin', value: 'pumpkin' },
    { label: 'Salted Caramel', value: 'salted-caramel' },
    { label: 'Strawberry', value: 'strawberry' },
    { label: 'Vanilla', value: 'vanilla' }
  ];

  return (
    <Combobox.Root autocomplete="list" defaultFilter="contains">
      <Combobox.TextInput
        aria-label="Food"
        placeholder="Select favorite food…"
        endElement={<Combobox.Clear label="Clear" />}
      />
      <Combobox.Content>
        {itemsToFilter.map(({ value, label }) => (
          <Combobox.Item key={value} value={value}>
            {label}
          </Combobox.Item>
        ))}
        <Combobox.NoValueFound>{'No options found.'}</Combobox.NoValueFound>
      </Combobox.Content>
    </Combobox.Root>
  );
};
```

### With a clear button

Use `Combobox.Clear` component to render a button that clears the selection of the combobox.
Focus will automatically move back to the `Combobox.TextInput` after the value is cleared.

<Callout variant="tip">

`Combobox.Clear` will not render itself when the combobox has no value.

</Callout>

```jsx
<Combobox.Root defaultValue="grape">
  <Combobox.TextInput
    aria-label="Fruit"
    placeholder="Select favorite fruit…"
    endElement={<Combobox.Clear label="Clear" />}
  />
  <Combobox.Content>
    <Combobox.Item value="apple">{'Apple'}</Combobox.Item>
    <Combobox.Item value="banana">{'Banana'}</Combobox.Item>
    <Combobox.Item value="grape">{'Grape'}</Combobox.Item>
    <Combobox.Item value="orange">{'Orange'}</Combobox.Item>
  </Combobox.Content>
</Combobox.Root>
```

### Custom value

By default, the value must be chosen from a predefined set of values. Use `allowsCustomValue` prop to indicate that text value doesn't have to match one of items value, and can be accepted by the combobox.

After typing, if the user presses <Kbd>Enter</Kbd> key or clicks out of the combobox without choosing a value from the list, the typed string becomes the value of the combobox.

<Callout variant="tip">

Use `Combobox.NoValueFound` to provide feedback that user entered text value does not match any of the predefined values and can be created.

</Callout>

```jsx
() => {
  const [value, setValue] = React.useState('');
  const [textValue, setTextValue] = React.useState('');

  return (
    <Flex flow="column">
      {value ? <Box>{`Selected value: ${value}`}</Box> : null}
      <Combobox.Root
        allowsCustomValue
        autocomplete="list"
        value={value}
        onValueChange={setValue}
        textValue={textValue}
        onTextValueChange={setTextValue}
      >
        <Combobox.TextInput
          aria-label="Fruit"
          placeholder="Select favorite fruit…"
        />
        <Combobox.Content>
          <Combobox.Item value="apple">{'Apple'}</Combobox.Item>
          <Combobox.Item value="avocado">{'Avocado'}</Combobox.Item>
          <Combobox.Item value="banana">{'Banana'}</Combobox.Item>
          <Combobox.Item value="kiwi">{'Kiwi'}</Combobox.Item>
          <Combobox.Item value="mango">{'Mango'}</Combobox.Item>
          <Combobox.Item value="orange">{'Orange'}</Combobox.Item>
          <Combobox.Item value="grapes">{'Grapes'}</Combobox.Item>
          <Combobox.Item value="strawberry">{'Strawberry'}</Combobox.Item>
          <Combobox.Item value="pineapple">{'Pineapple'}</Combobox.Item>
          <Combobox.NoValueFound>
            {'No matches for “'}
            <b>{textValue}</b>
            {'”'}
            <br />
            {'Press'} <Kbd>{'Enter'}</Kbd> {'to create custom value.'}
          </Combobox.NoValueFound>
        </Combobox.Content>
      </Combobox.Root>
    </Flex>
  );
};
```

### Disabled

`Combobox` can use `isDisabled` prop to prevent user from interacting, but also single items can be disabled to limit user's choice.

```jsx
() => {
  return (
    <Flex flow="column">
      <Combobox.Root isDisabled>
        <Combobox.TextInput
          aria-label="Language"
          placeholder="Select language"
          endElement={<Combobox.Clear label="Clear" />}
        />
        <Combobox.Content>
          <Combobox.Item value="en">{'English'}</Combobox.Item>
          <Combobox.Item value="fr">{'French'}</Combobox.Item>
        </Combobox.Content>
      </Combobox.Root>
      <Combobox.Root>
        <Combobox.TextInput
          aria-label="Language"
          placeholder="Select language"
          endElement={<Combobox.Clear label="Clear" />}
        />
        <Combobox.Content>
          <Combobox.Item value="en" isDisabled>
            {'English'}
          </Combobox.Item>
          <Combobox.Item value="fr" isDisabled>
            {'French'}
          </Combobox.Item>
          <Combobox.Item value="de">{'German'}</Combobox.Item>
          <Combobox.Item value="es">{'Spanish'}</Combobox.Item>
          <Combobox.Item isDisabled value="pt">
            {'Portuguese'}
          </Combobox.Item>
          <Combobox.Item value="ko">{'Korean'}</Combobox.Item>
        </Combobox.Content>
      </Combobox.Root>
    </Flex>
  );
};
```

### With Form Field

Use [Form Field component](/components/forms/form-field) to enhance `Combobox` with: an accessible label, an optional helper text, a feedback message or to show required indicator.

It is recommended to wrap comboboxes with [Form Field](/components/forms/form-field) to create a consistent set of accessible form fields.

<Callout variant="important">

When using `Combobox` without [Form Field](/components/forms/form-field), be mindful to provide `aria-label` for `Combobox.TextInput`.

</Callout>

```jsx
() => {
  const list = [
    'Apple',
    'Bacon',
    'Banana',
    'Broccoli',
    'Burger',
    'Cake',
    'Candy',
    'Carrot',
    'Cherry',
    'Chocolate',
    'Cookie',
    'Cucumber',
    'Donut',
    'Fish',
    'Fries',
    'Grape',
    'Green apple',
    'Hot dog',
    'Ice cream',
    'Kiwi',
    'Lemon',
    'Lollipop',
    'Onion',
    'Orange',
    'Pasta',
    'Pineapple',
    'Pizza',
    'Potato',
    'Salad',
    'Sandwich',
    'Steak',
    'Strawberry',
    'Tomato',
    'Watermelon'
  ];
  const [value, setValue] = React.useState('');

  return (
    <FormField.Root
      as={Flex}
      flow="column"
      isRequired
      validationStatus={!value ? 'error' : undefined}
    >
      <FormField.Label>{'Food'}</FormField.Label>
      <Combobox.Root value={value} onValueChange={setValue}>
        <Combobox.TextInput
          placeholder="My favorite food is…"
          endElement={<Combobox.Clear label="Clear" />}
        />
        <Combobox.Content>
          {list.map(value => (
            <Combobox.Item key={value} value={value}>
              {value}
            </Combobox.Item>
          ))}
        </Combobox.Content>
      </Combobox.Root>
      <FormField.FeedbackMessage>
        <FormField.FeedbackIcon />
        {'Feedback message.'}
      </FormField.FeedbackMessage>
    </FormField.Root>
  );
};
```

### Sizes

`Combobox` comes in two size variants: `medium` and `small`, with the `medium` size used by default. All sizes are aligned with sizes of other related components like [Text Input](/components/forms/text-input).

```jsx
() => {
  const animals = [
    { label: 'Bear', value: 'bear' },
    { label: 'Dog', value: 'dog' },
    { label: 'Elephant', value: 'elephant' },
    { label: 'Parrot', value: 'parrot' },
    { label: 'Raccoon', value: 'raccoon' },
    { label: 'Seal', value: 'Seal' }
  ];

  return (
    <ContentBlock max="measureMedium" center={false} gutters="none">
      <Flex flow="column">
        <FormField.Root as={Flex} flow="column" size="small">
          <FormField.Label>{'Animal'}</FormField.Label>
          <Combobox.Root size="small">
            <Combobox.TextInput endElement={<Combobox.Clear label="Clear" />} />
            <Combobox.Content>
              {animals.map(({ value, label }) => (
                <Combobox.Item key={value} value={value}>
                  {label}
                </Combobox.Item>
              ))}
            </Combobox.Content>
          </Combobox.Root>
        </FormField.Root>
        <FormField.Root as={Flex} flow="column">
          <FormField.Label>{'Animal'}</FormField.Label>
          <Combobox.Root>
            <Combobox.TextInput endElement={<Combobox.Clear label="Clear" />} />
            <Combobox.Content>
              {animals.map(({ value, label }) => (
                <Combobox.Item key={value} value={value}>
                  {label}
                </Combobox.Item>
              ))}
            </Combobox.Content>
          </Combobox.Root>
        </FormField.Root>
      </Flex>
    </ContentBlock>
  );
};
```

### Customized appearance

`Combobox.TextInput` and `Combobox.Item` can be decorated with supporting icons or elements
using `startElement` and `endElement` props.

```jsx
() => {
  const [value, setValue] = React.useState('');
  const minutes = [
    { label: 'Quarter', value: 15, color: 'success' },
    { label: 'Half hour', value: 30, color: 'success' },
    { label: 'Hour', value: 60, color: 'warning' },
    { label: 'Two hours', value: 120, color: 'danger' }
  ];

  return (
    <ContentBlock max="measureNarrow" center={false} gutters="none">
      <Flex flow="column">
        <Combobox.Root value={value} onValueChange={setValue} size="small">
          <Combobox.TextInput
            placeholder="Select timespan"
            startElement={
              value ? (
                <Flex gap="spacingXs">
                  <SvgIcon iconName="time" />
                  <Label
                    size="small"
                    circular
                    variant="subtle"
                    color={minutes.find(option => option.value === value).color}
                  >{`${value} min`}</Label>
                </Flex>
              ) : (
                <SvgIcon iconName="time" />
              )
            }
            endElement={<Combobox.Clear label="Clear" />}
          />
          <Combobox.Content>
            {minutes.map(({ value, label, color }) => (
              <Combobox.Item key={value} value={value}>
                {label}
              </Combobox.Item>
            ))}
          </Combobox.Content>
        </Combobox.Root>
        <Combobox.Root>
          <Combobox.TextInput
            startElement={<SvgIcon iconName="search" />}
            endElement={<Combobox.Clear label="Clear" />}
            placeholder="Change status…"
          />
          <Combobox.Content>
            <Combobox.Item
              value="backlog"
              startElement={<SvgIcon iconName="help" />}
              endElement={
                <Label size="small" circular>
                  {'8'}
                </Label>
              }
            >
              {'Backlog'}
            </Combobox.Item>
            <Combobox.Item
              value="todo"
              startElement={<SvgIcon iconName="tasks" />}
              endElement={
                <Label size="small" circular>
                  {'8'}
                </Label>
              }
            >
              {'Todo'}
            </Combobox.Item>
            <Combobox.Item
              value="in-progress"
              startElement={<SvgIcon iconName="loading" />}
              endElement={
                <Label size="small" circular>
                  {'3'}
                </Label>
              }
            >
              {'In Progress'}
            </Combobox.Item>
            <Combobox.Item
              value="done"
              startElement={<SvgIcon iconName="check" />}
              endElement={
                <Label size="small" circular>
                  {'4'}
                </Label>
              }
            >
              {'Done'}
            </Combobox.Item>
            <Combobox.Item
              value="cancelled"
              startElement={<SvgIcon iconName="close" />}
              endElement={
                <Label size="small" circular>
                  {'10'}
                </Label>
              }
            >
              {'Cancelled'}
            </Combobox.Item>
          </Combobox.Content>
        </Combobox.Root>
      </Flex>
    </ContentBlock>
  );
};
```

### Active indicators

When item inside the `Combobox` is selected its text content is highlighted in bold.
For additional emphasis you may include `Combobox.ItemIndicator` to add a visual indicator rendered when the item is selected.

```jsx
() => {
  const languages = [
    { label: 'English', value: 'en' },
    { label: 'French', value: 'fr' },
    { label: 'German', value: 'de' },
    { label: 'Spanish', value: 'es' },
    { label: 'Portuguese', value: 'pt' },
    { label: 'Russian', value: 'ru' }
  ];

  return (
    <ContentBlock max="measureNarrow" center={false} gutters="none">
      <Combobox.Root>
        <Combobox.TextInput
          placeholder="Select language"
          endElement={<Combobox.Clear label="Clear" />}
        />
        <Combobox.Content>
          {languages.map(({ value, label }) => (
            <Combobox.Item
              key={value}
              value={value}
              startElement={<Combobox.ItemIndicator />}
            >
              {label}
            </Combobox.Item>
          ))}
        </Combobox.Content>
      </Combobox.Root>
    </ContentBlock>
  );
};
```

### HTML Form integration

When used in the context of an HTML form, `Combobox` automatically renders hidden input element that is kept in sync with the selected value.

You just need to provide `name` property that will be used when submitting the form.

```jsx
() => {
  const handleSubmit = event => {
    event.preventDefault();
    const formData = new FormData(event.currentTarget);
    const formJson = Object.fromEntries(formData.entries());
    alert(JSON.stringify(formJson));
  };

  return (
    <form onSubmit={handleSubmit}>
      <Flex flow="column">
        <FormField.Root as={Flex} flow="column">
          <FormField.Label>{'City'}</FormField.Label>
          <Combobox.Root name="city">
            <Combobox.TextInput endElement={<Combobox.Clear label="Clear" />} />
            <Combobox.Content>
              <Combobox.Item value="rome">{'Rome'}</Combobox.Item>
              <Combobox.Item value="oslo">{'Oslo'}</Combobox.Item>
              <Combobox.Item value="paris">{'Paris'}</Combobox.Item>
              <Combobox.Item value="ny">{'New York'}</Combobox.Item>
            </Combobox.Content>
          </Combobox.Root>
        </FormField.Root>
        <Box>
          <Button type="submit">{'Submit'}</Button>
        </Box>
      </Flex>
    </form>
  );
};
```

---

## Accessibility features

<ul>
  <li iconName="check">

Exposed to assistive technology as a combobox using the [WAI ARIA Combobox design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/).

  </li>
  <li iconName="check">

Provides deep keyboard interactions.

  </li>
</ul>

---

## API Reference

### Combobox.Root

| Name                   | Type                                                                                   | Default        | Description                                                                                                                             | Required |
| ---------------------- | -------------------------------------------------------------------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `value`                | `string`                                                                               |                | The controlled selected value of the combobox. Use in conjunction with `onValueChange`.                                                 |          |
| `defaultValue`         | `string`                                                                               |                | The selected value of the combobox when initially rendered. Use when you do not need to control the selection state.                    |          |
| `onValueChange`        | `(value: string) => void`                                                              |                | Event handler called when the selection state changes.                                                                                  |          |
| `textValue`            | `string`                                                                               |                | The controlled value of the `Combobox.TextInput`. Use in conjunction with `onTextValueChange`.                                          |          |
| `defaultTextValue`     | `string`                                                                               |                | The value of the `Combobox.TextInput` when first rendered. Use when you do not need to control the text input state.                    |          |
| `onTextValueChange`    | `(value: string) => void`                                                              |                | Event handler called when the text input state changes.                                                                                 |          |
| `isOpen`               | `boolean`                                                                              | `false`        | The controlled open state of the combobox. Use in conjunction with `onIsOpenChange`.                                                    |          |
| `defaultIsOpen`        | `boolean`                                                                              |                | The open state of the combobox when it's first rendered. Use when you do not need to control open state.                                |          |
| `onIsOpenChange`       | `(isOpen: boolean) => void`                                                            |                | Event handler called when the open state of the combobox changes.                                                                       |          |
| `size`                 | `"small" \| "medium"`                                                                  | `"medium"`     | The size of the combobox.                                                                                                               |          |
| `autocomplete`         | `"none" \| "list"`                                                                     | `"none"`       | The type of autocomplete functionality. When `list`, text typed inside of `Combobox.TextInput` filters the list of combobox items.      |          |
| `defaultFilter`        | `"startsWith" \| "contains" \| (itemTextValue: string, inputValue: string) => boolean` | `"startsWith"` | The filter function used to determine if an item should be included in the combobox list. Use in conjunction with `autocomplete="list"` |          |
| `locale`               | `string`                                                                               | `"en-EN"`      | Locale which is used for language-sensitive string comparison during filtering of the combobox items.                                   |          |
| `allowsCustomValue`    | `boolean`                                                                              | `false`        | When `true`, combobox allows a non-item matching input value to be set.                                                                 |          |
| `isDisabled`           | `boolean`                                                                              | `false`        | When `true`, the combobox will be disabled, preventing the user from interacting with it.                                               |          |
| `isPrintableCharacter` | `(str: string) => boolean`                                                             |                | Allows to override the default function for determining if the character typed in the `Combobox.TextInput` is considered printable.     |          |
| `name`                 | `string`                                                                               |                | Name attribute of the hidden input element, used when submitting an HTML form.                                                          |          |

### Combobox.TextInput

| Name                      | Type                 | Default | Description                                                                                                                                                                                                                                   | Required |
| ------------------------- | -------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `css`                     | `StitchesCss`        |         | Apply styles directly to a component in a similar way how you would define inline styles. Vera uses [Stitches](https://stitches.dev/) under the hood with a fully-typed API and support for features like tokens, media queries, or variants. |          |
| `startElement`            | `React.ReactElement` |         | `ReactElement` to render to the left of the text input.                                                                                                                                                                                       |          |
| `endElement`              | `React.ReactElement` |         | `ReactElement` to render to the right of the text input.                                                                                                                                                                                      |          |
| `shouldShowOpenIndicator` | `boolean`            | `true`  | When `true`, a chevron icon is displayed next to the input for indicating open/close state of the listbox.                                                                                                                                    |          |

### Combobox.Content

| Name             | Type                                                                                                     | Default      | Description                                                                                                                                                                                                                                   | Required |
| ---------------- | -------------------------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `css`            | `StitchesCss`                                                                                            |              | Apply styles directly to a component in a similar way how you would define inline styles. Vera uses [Stitches](https://stitches.dev/) under the hood with a fully-typed API and support for features like tokens, media queries, or variants. |          |
| `placement`      | `"top" \| "top_left" \| "top_right" \| "bottom" \| "bottom_left" \| "bottom_right" \| "left" \| "right"` | `"bottom"`   | Placement of the content being positioned on.                                                                                                                                                                                                 |          |
| `anchorOffset`   | `number`                                                                                                 |              | Distance from the anchor to the element being positioned.                                                                                                                                                                                     |          |
| `onExitComplete` | `() => void`                                                                                             | `() => void` | Event handler called when the content has completed animating out.                                                                                                                                                                            |          |

### Combobox.Clear

| Name    | Type          | Default | Description                                                                                                                                                                                                                                   | Required |
| ------- | ------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `css`   | `StitchesCss` |         | Apply styles directly to a component in a similar way how you would define inline styles. Vera uses [Stitches](https://stitches.dev/) under the hood with a fully-typed API and support for features like tokens, media queries, or variants. |          |
| `label` | `string`      |         | The `aria-label` of the button to use for screen readers.                                                                                                                                                                                     | Yes      |

### Combobox.Item

| Name           | Type                                                      | Default | Description                                                                                                                                                                                                                                                                                  | Required |
| -------------- | --------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `as`           | `keyof JSX.IntrinsicElements \| React.ComponentType<any>` | `div`   | Change the component to a different HTML tag or custom component. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.   For more details, read our [Composition](/get-started/composition#polymorphism) guide. |          |
| `css`          | `StitchesCss`                                             |         | Apply styles directly to a component in a similar way how you would define inline styles. Vera uses [Stitches](https://stitches.dev/) under the hood with a fully-typed API and support for features like tokens, media queries, or variants.                                                |          |
| `value`        | `string`                                                  |         | The value of the combobox item.                                                                                                                                                                                                                                                              | Yes      |
| `isDisabled`   | `boolean`                                                 |         | When `true`, the item will be disabled, preventing the user from interacting with it.                                                                                                                                                                                                        |          |
| `textValue`    | `string`                                                  |         | By default the search behavior will use the `textContent` of the `Combobox.ItemText`. When the content is complex or non-textual, this property can be used to specify optional text for the item search purposes.                                                                           |          |
| `startElement` | `React.ReactElement`                                      |         | `ReactElement` to render to the left of the item's children.                                                                                                                                                                                                                                 |          |
| `endElement`   | `React.ReactElement`                                      |         | `ReactElement` to render to the right of the item's children.                                                                                                                                                                                                                                |          |

### Combobox.ItemText

| Name | Type                                                      | Default | Description                                                                                                                                                                                                                                                                                  | Required |
| ---- | --------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `as` | `keyof JSX.IntrinsicElements \| React.ComponentType<any>` | `span`  | Change the component to a different HTML tag or custom component. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.   For more details, read our [Composition](/get-started/composition#polymorphism) guide. |          |

### Combobox.ItemIndicator

| Name  | Type                                                      | Default | Description                                                                                                                                                                                                                                                                                  | Required |
| ----- | --------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `as`  | `keyof JSX.IntrinsicElements \| React.ComponentType<any>` | `div`   | Change the component to a different HTML tag or custom component. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.   For more details, read our [Composition](/get-started/composition#polymorphism) guide. |          |
| `css` | `StitchesCss`                                             |         | Apply styles directly to a component in a similar way how you would define inline styles. Vera uses [Stitches](https://stitches.dev/) under the hood with a fully-typed API and support for features like tokens, media queries, or variants.                                                |          |

### Combobox.NoValueFound

| Name  | Type                                                      | Default | Description                                                                                                                                                                                                                                                                                  | Required |
| ----- | --------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `as`  | `keyof JSX.IntrinsicElements \| React.ComponentType<any>` | `div`   | Change the component to a different HTML tag or custom component. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node.   For more details, read our [Composition](/get-started/composition#polymorphism) guide. |          |
| `css` | `StitchesCss`                                             |         | Apply styles directly to a component in a similar way how you would define inline styles. Vera uses [Stitches](https://stitches.dev/) under the hood with a fully-typed API and support for features like tokens, media queries, or variants.                                                |          |