# Multi Select Menu
> Input control allowing for choosing multiple options from searchable options menu.

<Callout variant="tip">

`MultiSelectMenu` is built on top of [Select Menu](/components/forms/select-menu/select-menu) parts which provide core functionality of the component.

</Callout>

## Import

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

Multi Select Menu is a compound component that consists of multiple parts:

- `MultiSelectMenu.Root`: The wrapper that contains all the parts of a select menu and provides context for its children.
- `MultiSelectMenu.Trigger`: The button that toggles the select menu.
- `MultiSelectMenu.Content`: A wrapper for the content to be rendered when the select menu is open. It positions itself by aligning over `MultiSelectMenu.Trigger`.
- `MultiSelectMenu.Clear`: The button that clears the value(s) of select menu.
- `MultiSelectMenu.Item`: A container for select menu's item of choice.
- `MultiSelectMenu.ItemText`: A wrapper around textual part of `MultiSelectMenu.Item`.
- `MultiSelectMenu.Group`: A wrapper for the group of select menu items.
- `MultiSelectMenu.Label`: The component that renders an accessible label of `MultiSelectMenu.Group`.
- `MultiSelectMenu.NestedGroup`: A wrapper for the checkbox-like group of select menu items.
- `MultiSelectMenu.NestedGroupLabel`: The component that renders selectable label of `MultiSelectMenu.NestedGroup`
- `MultiSelectMenu.Separator`: The component that renders a horizontal divider between menu items and groups.

## Examples

### Basic

In contrast with [Single Select Menu](/components/forms/select-menu/single-select-menu), the options popup of `MultiSelectMenu` doesn't close after an item is selected, which enables users to continue choosing more options.
`MultiSelectMenu` items are visually distinct from the [Single Select Menu](/components/forms/select-menu/single-select-menu) items, to indicate multiple selection.

<Callout variant="tip">

Provide `placeholder` prop when the select input does not have an initial value.

</Callout>

<Callout variant="tip">

`MultiSelectMenu` has built in typeahead behavior, meaning pressing the letter <Kbd>B</Kbd> will jump to and highlight the word "Banana" in the example below.

</Callout>

```jsx
<MultiSelectMenu.Root>
  <MultiSelectMenu.Trigger
    aria-label="Favorite fruit(s)"
    placeholder="Select favorite fruit(s)…"
  />
  <MultiSelectMenu.Content>
    <MultiSelectMenu.Item value="apple">{'Apple'}</MultiSelectMenu.Item>
    <MultiSelectMenu.Item value="banana">{'Banana'}</MultiSelectMenu.Item>
    <MultiSelectMenu.Item value="grape">{'Grape'}</MultiSelectMenu.Item>
    <MultiSelectMenu.Item value="orange">{'Orange'}</MultiSelectMenu.Item>
  </MultiSelectMenu.Content>
</MultiSelectMenu.Root>
```

### With a default value

When using `MultiSelectMenu` in "uncontrolled" mode, you can specify the default selected options with `defaultValue` property.

```jsx
<MultiSelectMenu.Root defaultValue={['white', 'green']}>
  <MultiSelectMenu.Trigger aria-label="Color" />
  <MultiSelectMenu.Content>
    <MultiSelectMenu.Item value="white">{'White'}</MultiSelectMenu.Item>
    <MultiSelectMenu.Item value="red">{'Red'}</MultiSelectMenu.Item>
    <MultiSelectMenu.Item value="green">{'Green'}</MultiSelectMenu.Item>
    <MultiSelectMenu.Item value="purple">{'Purple'}</MultiSelectMenu.Item>
  </MultiSelectMenu.Content>
</MultiSelectMenu.Root>
```

### Controlled

You can easily make the `MultiSelectMenu` 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(['apple']);

  return (
    <Flex flow="column">
      <MultiSelectMenu.Root value={value} onValueChange={setValue}>
        <MultiSelectMenu.Trigger
          aria-label="Favorite fruit(s)"
          placeholder="Select favorite fruit(s)…"
        />
        <MultiSelectMenu.Content>
          <MultiSelectMenu.Item value="apple">{'Apple'}</MultiSelectMenu.Item>
          <MultiSelectMenu.Item value="banana">{'Banana'}</MultiSelectMenu.Item>
          <MultiSelectMenu.Item value="grape">{'Grape'}</MultiSelectMenu.Item>
          <MultiSelectMenu.Item value="orange">{'Orange'}</MultiSelectMenu.Item>
        </MultiSelectMenu.Content>
      </MultiSelectMenu.Root>
      <Box>Selected values: {value.join(', ')}</Box>
    </Flex>
  );
};
```

### With a clear button

Use `MultiSelectMenu.Clear` part to render a button that clears the value of the select menu.
Focus will automatically move back to the select menu trigger after the value is cleared.

`MultiSelectMenu.Clear` will not render itself when the select menu has no value.

```jsx
<MultiSelectMenu.Root defaultValue={['white', 'red', 'purple']}>
  <MultiSelectMenu.Trigger
    aria-label="Colors"
    placeholder="Pick colors..."
    endElement={<MultiSelectMenu.Clear label="Clear all" />}
  />
  <MultiSelectMenu.Content>
    <MultiSelectMenu.Item value="white">{'White'}</MultiSelectMenu.Item>
    <MultiSelectMenu.Item value="red">{'Red'}</MultiSelectMenu.Item>
    <MultiSelectMenu.Item value="green">{'Green'}</MultiSelectMenu.Item>
    <MultiSelectMenu.Item value="purple">{'Purple'}</MultiSelectMenu.Item>
  </MultiSelectMenu.Content>
</MultiSelectMenu.Root>
```

### With labels

You can pass the `withLabels` prop which will render the selected values as [Labels](/components/label#removable-label) that can be individually removed.
This presentation is useful for visually representing multiple active filters.

```jsx
<MultiSelectMenu.Root defaultValue={['documentation', 'feature']}>
  <MultiSelectMenu.Trigger
    aria-label="Tags"
    placeholder="Pick tags..."
    withLabels
    endElement={<MultiSelectMenu.Clear label="Clear" />}
  />
  <MultiSelectMenu.Content>
    <MultiSelectMenu.Item value="documentation">
      {'documentation'}
    </MultiSelectMenu.Item>
    <MultiSelectMenu.Item value="feature">{'feature'}</MultiSelectMenu.Item>
    <MultiSelectMenu.Item value="bug">{'bug'}</MultiSelectMenu.Item>
    <MultiSelectMenu.Item value="critical">{'critical'}</MultiSelectMenu.Item>
    <MultiSelectMenu.Item value="blocked">{'blocked'}</MultiSelectMenu.Item>
    <MultiSelectMenu.Item value="low-priority">
      {'low priority'}
    </MultiSelectMenu.Item>
  </MultiSelectMenu.Content>
</MultiSelectMenu.Root>
```

### Disabled

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

```jsx
() => {
  const items = ['Carrot', 'Corn', 'Broccoli', 'Tomato', 'Paprika'];

  return (
    <Flex flow="column">
      <MultiSelectMenu.Root isDisabled defaultValue={items.slice(0, 2)}>
        <MultiSelectMenu.Trigger />
        <MultiSelectMenu.Content>
          {items.map(item => (
            <MultiSelectMenu.Item key={item} value={item}>
              {item}
            </MultiSelectMenu.Item>
          ))}
        </MultiSelectMenu.Content>
      </MultiSelectMenu.Root>
      <MultiSelectMenu.Root isDisabled defaultValue={items.slice(0, 3)}>
        <MultiSelectMenu.Trigger withLabels />
        <MultiSelectMenu.Content>
          {items.map(item => (
            <MultiSelectMenu.Item key={item} value={item}>
              {item}
            </MultiSelectMenu.Item>
          ))}
        </MultiSelectMenu.Content>
      </MultiSelectMenu.Root>
      <MultiSelectMenu.Root>
        <MultiSelectMenu.Trigger placeholder="I have disabled red veggies" />
        <MultiSelectMenu.Content>
          {items.map((item, index) => (
            <MultiSelectMenu.Item
              key={item}
              value={item}
              isDisabled={index >= 3}
            >
              {item}
            </MultiSelectMenu.Item>
          ))}
        </MultiSelectMenu.Content>
      </MultiSelectMenu.Root>
    </Flex>
  );
};
```

### With Form Field

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

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

<Callout variant="tip">

The [Form Field](/components/forms/form-field) automatically generates a unique id that links the `MultiSelectMenu` with the `FormField.Label`.

</Callout>

<Callout variant="important">

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

</Callout>

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

  return (
    <FormField.Root
      as={Flex}
      flow="column"
      isRequired
      validationStatus={value.length === 0 ? 'error' : undefined}
    >
      <FormField.Label as="div">{'Seasons'}</FormField.Label>
      <MultiSelectMenu.Root value={value} onValueChange={setValue}>
        <MultiSelectMenu.Trigger placeholder="Pick relevant seasons" />
        <MultiSelectMenu.Content>
          <MultiSelectMenu.Item value="winter">{'Winter'}</MultiSelectMenu.Item>
          <MultiSelectMenu.Item value="spring">{'Spring'}</MultiSelectMenu.Item>
          <MultiSelectMenu.Item value="summer">{'Summer'}</MultiSelectMenu.Item>
          <MultiSelectMenu.Item value="fall">{'Fall'}</MultiSelectMenu.Item>
        </MultiSelectMenu.Content>
      </MultiSelectMenu.Root>
      <FormField.FeedbackMessage>
        <FormField.FeedbackIcon />
        {'Choose at least one season.'}
      </FormField.FeedbackMessage>
    </FormField.Root>
  );
};
```

### Sizes

`MultiSelectMenu` 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
<Flex flow="column">
  <FormField.Root as={Flex} flow="column" size="small">
    <FormField.Label as="div">{'Timespan'}</FormField.Label>
    <MultiSelectMenu.Root size="small">
      <MultiSelectMenu.Trigger withLabels placeholder="Select timespan" />
      <MultiSelectMenu.Content>
        <MultiSelectMenu.Item value="quarter">{'Quarter'}</MultiSelectMenu.Item>
        <MultiSelectMenu.Item value="halfHour">
          {'Half hour'}
        </MultiSelectMenu.Item>
        <MultiSelectMenu.Item value="hour">{'Hour'}</MultiSelectMenu.Item>
      </MultiSelectMenu.Content>
    </MultiSelectMenu.Root>
  </FormField.Root>
  <FormField.Root as={Flex} flow="column">
    <FormField.Label as="div">{'Timespan'}</FormField.Label>
    <MultiSelectMenu.Root>
      <MultiSelectMenu.Trigger placeholder="Select timespan" />
      <MultiSelectMenu.Content>
        <MultiSelectMenu.Item value="quarter">{'Quarter'}</MultiSelectMenu.Item>
        <MultiSelectMenu.Item value="halfHour">
          {'Half hour'}
        </MultiSelectMenu.Item>
        <MultiSelectMenu.Item value="hour">{'Hour'}</MultiSelectMenu.Item>
      </MultiSelectMenu.Content>
    </MultiSelectMenu.Root>
  </FormField.Root>
</Flex>
```

### Customized appearance

`MultiSelectMenu.Trigger` can be decorated with supporting icons or elements
using `startElement` and `endElement` props. `MultiSelectMenu.Item` can have additional `endElement` specified.

```jsx
() => {
  const [value, setValue] = React.useState([]);
  const minutes = {
    quarter: 15,
    halfHour: 30,
    hour: 60,
    twoHours: 120
  };

  return (
    <ContentBlock max="measureMedium" center={false} gutters="none">
      <MultiSelectMenu.Root value={value} onValueChange={setValue}>
        <MultiSelectMenu.Trigger
          aria-label="Timestamps"
          placeholder="Select timespans"
          startElement={<SvgIcon iconName="time" />}
          endElement={
            value.length > 0 && (
              <Label size="small" circular>
                {value.length <= 1
                  ? minutes[value] + ' min'
                  : value.reduce((a, b) => a + minutes[b], 0) + ' min'}
              </Label>
            )
          }
        />
        <MultiSelectMenu.Content>
          <MultiSelectMenu.Item
            value="quarter"
            endElement={
              <Label size="small" circular>
                {'0.25 h'}
              </Label>
            }
          >
            {'Quarter'}
          </MultiSelectMenu.Item>
          <MultiSelectMenu.Item
            value="halfHour"
            endElement={
              <Label size="small" circular>
                {'0.5 h'}
              </Label>
            }
          >
            {'Half hour'}
          </MultiSelectMenu.Item>
          <MultiSelectMenu.Item
            value="hour"
            startElement={
              <Tooltip content="Most commonly used">
                <SvgIcon iconName="star" />
              </Tooltip>
            }
            endElement={
              <Label size="small" circular>
                {'1 h'}
              </Label>
            }
          >
            {'Hour'}
          </MultiSelectMenu.Item>
          <MultiSelectMenu.Item
            value="twoHours"
            endElement={
              <Label size="small" circular>
                {'2 h'}
              </Label>
            }
          >
            {'Two hours'}
          </MultiSelectMenu.Item>
        </MultiSelectMenu.Content>
      </MultiSelectMenu.Root>
    </ContentBlock>
  );
};
```

### Groups

Related options can be grouped together using `MultiSelectMenu.Group` with `MultiSelectMenu.Label` as a label for the group.

<Callout variant="tip">

Notice how overflowing content behaves when there is a long list of select
menu items.

</Callout>

<Callout variant="tip">

When you open the menu, last selected item is focused and scrolled into view if necessary.

</Callout>

```jsx
() => {
  const group = {
    Land: ['Cat', 'Dog', 'Tiger', 'Reindeer', 'Raccoon', 'Armadillo'],
    Water: ['Dolphin', 'Flounder', 'Eel'],
    Air: [
      'Falcon',
      'Winged Horse',
      'Owl',
      'Raven',
      'Parrot',
      'Blue jay',
      'Sparrow',
      'Magpie',
      'Pigeon',
      'Canary',
      'Kingfisher',
      'Blackbird',
      'Bald eagle',
      'Hawk',
      'Woodpecker'
    ]
  };

  return (
    <ContentBlock max="measureMedium" center={false} gutters="none">
      <FormField.Root as={Flex} flow="column">
        <FormField.Label>{'Your favorite animals'}</FormField.Label>
        <MultiSelectMenu.Root>
          <MultiSelectMenu.Trigger
            placeholder="Choose your animals"
            endElement={<MultiSelectMenu.Clear label="Clear all" />}
            withLabels
          />
          <MultiSelectMenu.Content>
            {Object.entries(group).map(([name, animals], index) => (
              <React.Fragment key={name}>
                {index !== 0 && <MultiSelectMenu.Separator />}
                <MultiSelectMenu.Group>
                  <MultiSelectMenu.Label>
                    {name} {`(${animals.length})`}
                  </MultiSelectMenu.Label>
                  {animals.map(animal => (
                    <MultiSelectMenu.Item key={animal} value={animal}>
                      {animal}
                    </MultiSelectMenu.Item>
                  ))}
                </MultiSelectMenu.Group>
              </React.Fragment>
            ))}
          </MultiSelectMenu.Content>
        </MultiSelectMenu.Root>
      </FormField.Root>
    </ContentBlock>
  );
};
```

### Nested groups

`MultiSelectMenu` supports nesting of selectable groups through `MultiSelectMenu.NestedGroup` and `MultiSelectMenu.NestedGroupLabel` parts.

Partially selected groups are presented as <Link href="/components/forms/checkbox#indeterminate-state">checkboxes with indeterminate state</Link>.

```jsx
<ContentBlock max="measureMedium" center={false} gutters="none">
  <FormField.Root as={Flex} flow="column">
    <FormField.Label>{'Your favorite food'}</FormField.Label>
    <MultiSelectMenu.Root>
      <MultiSelectMenu.Trigger
        placeholder="My favorite food is…"
        withLabels
        endElement={<MultiSelectMenu.Clear label="Clear all" />}
      />
      <MultiSelectMenu.Content>
        <MultiSelectMenu.NestedGroup>
          <MultiSelectMenu.NestedGroupLabel>
            {'Fruits'}
          </MultiSelectMenu.NestedGroupLabel>
          <MultiSelectMenu.NestedGroup>
            <MultiSelectMenu.NestedGroupLabel>
              {'Green fruits'}
            </MultiSelectMenu.NestedGroupLabel>
            <MultiSelectMenu.Item value="apple">{'Apple'}</MultiSelectMenu.Item>
            <MultiSelectMenu.Item value="avocado">
              {'Avocado'}
            </MultiSelectMenu.Item>
            <MultiSelectMenu.Item value="kiwi">{'Kiwi'}</MultiSelectMenu.Item>
          </MultiSelectMenu.NestedGroup>
          <MultiSelectMenu.NestedGroup>
            <MultiSelectMenu.NestedGroupLabel>
              {'Orange fruits'}
            </MultiSelectMenu.NestedGroupLabel>
            <MultiSelectMenu.Item value="mango">{'Mango'}</MultiSelectMenu.Item>
            <MultiSelectMenu.Item value="orange">
              {'Orange'}
            </MultiSelectMenu.Item>
            <MultiSelectMenu.Item value="grapefruit">
              {'Grapefruit'}
            </MultiSelectMenu.Item>
          </MultiSelectMenu.NestedGroup>
        </MultiSelectMenu.NestedGroup>
        <MultiSelectMenu.NestedGroup>
          <MultiSelectMenu.NestedGroupLabel>
            {'Meat'}
          </MultiSelectMenu.NestedGroupLabel>
          <MultiSelectMenu.Item value="beef">{'Beef'}</MultiSelectMenu.Item>
          <MultiSelectMenu.Item value="chicken">
            {'Chicken'}
          </MultiSelectMenu.Item>
          <MultiSelectMenu.Item value="lamb">{'Lamb'}</MultiSelectMenu.Item>
        </MultiSelectMenu.NestedGroup>
      </MultiSelectMenu.Content>
    </MultiSelectMenu.Root>
  </FormField.Root>
</ContentBlock>
```

### Custom render value

By default, `MultiSelectMenu.Trigger` will automatically display the selected items text content separated with commas.

However you can take control over the rendering by providing a function to the `renderValue` prop. The function receives getter for the selected items. The element returned by this function will be rendered inside the trigger.

This can be useful to prevent listing all selected items inside the trigger when the list is long and horizontal space is at a premium.

<Callout type="warning">
  Notice that <InlineCode>renderValue</InlineCode> override{' '}
  <strong>cannot</strong> work together with <InlineCode>withLabels</InlineCode>{' '}
  prop.
</Callout>

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

  const list = [
    'Chocolate',
    'Vanilla',
    'Strawberry',
    'Caramel',
    'Mint',
    'Lemon',
    'Pistachio'
  ];

  return (
    <ContentBlock max="measureNarrow" center={false} gutters="none">
      <FormField.Root as={Flex} flow="column">
        <FormField.Label>{'Your favorite flavor'}</FormField.Label>
        <MultiSelectMenu.Root value={value} onValueChange={setValue}>
          <MultiSelectMenu.Trigger
            endElement={<MultiSelectMenu.Clear label="Clear all" />}
            placeholder="No flavor selected"
            renderValue={({ getSelectedItems }) => {
              const selectedItems = getSelectedItems();
              if (selectedItems.length > 0) {
                if (selectedItems.length === 1) {
                  return selectedItems[0].textValue;
                }

                return (
                  <Flex gap="spacingXs">
                    <Label size="small" circular color="info">
                      {selectedItems.length}
                    </Label>
                    {'flavours selected'}
                  </Flex>
                );
              }

              return null;
            }}
          />
          <MultiSelectMenu.Content>
            {list.map(value => (
              <MultiSelectMenu.Item key={value} value={value}>
                {value}
              </MultiSelectMenu.Item>
            ))}
          </MultiSelectMenu.Content>
        </MultiSelectMenu.Root>
      </FormField.Root>
    </ContentBlock>
  );
};
```

<Callout variant="tip">

If you return interactive elements i.e. buttons, call `stopPropagation()` from the `onPointerDown` event to prevent them from opening the options menu.

</Callout>

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

  const list = [
    'Action',
    'Adventure',
    'Comedy',
    'Drama',
    'Fantasy',
    'Horror',
    'Mystery',
    'Psychological',
    'Romance',
    'Sci-Fi',
    'Thriller',
    'Crime',
    'Autobiographical',
    'Historical'
  ];

  return (
    <ContentBlock max="measureNarrow" center={false} gutters="none">
      <FormField.Root as={Flex} flow="column">
        <FormField.Label as="div">{'Genre'}</FormField.Label>
        <MultiSelectMenu.Root value={value} onValueChange={setValue}>
          <MultiSelectMenu.Trigger
            placeholder="Any"
            endElement={<MultiSelectMenu.Clear label="Clear" />}
            renderValue={({ getSelectedItems }) => {
              const selectedItems = getSelectedItems();
              if (selectedItems.length > 0) {
                return (
                  <Flex gap="spacingXs" wrap="wrap">
                    <Label
                      variant="subtle"
                      onPointerDown={e => e.stopPropagation()}
                      onKeyDown={e => e.stopPropagation()}
                      onRemove={() =>
                        setValue(value =>
                          value.filter(v => v !== selectedItems[0].value)
                        )
                      }
                    >
                      {selectedItems[0].textValue}
                    </Label>
                    {selectedItems.length > 1 && (
                      <Label variant="subtle">
                        {`+${selectedItems.length - 1}`}
                      </Label>
                    )}
                  </Flex>
                );
              }

              return null;
            }}
          />
          <MultiSelectMenu.Content>
            {list.map(value => (
              <MultiSelectMenu.Item key={value} value={value}>
                {value}
              </MultiSelectMenu.Item>
            ))}
          </MultiSelectMenu.Content>
        </MultiSelectMenu.Root>
      </FormField.Root>
    </ContentBlock>
  );
};
```

### HTML Form integration

`MultiSelectMenu` automatically uses hidden select part from [Select Menu](/components/forms/select-menu/select-menu) when it's used in the context of an HTML form.

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);
    alert(JSON.stringify(Array.from(formData.entries())));
  };

  return (
    <form onSubmit={handleSubmit}>
      <Flex flow="column">
        <FormField.Root as={Flex} flow="column">
          <FormField.Label as="div">{'Favorite food'}</FormField.Label>
          <MultiSelectMenu.Root name="food">
            <MultiSelectMenu.Trigger
              placeholder="Select"
              endElement={<MultiSelectMenu.Clear label="Clear all" />}
            />
            <MultiSelectMenu.Content>
              <MultiSelectMenu.Item value="burger">
                {'Burger'}
              </MultiSelectMenu.Item>
              <MultiSelectMenu.Item value="cake">{'Cake'}</MultiSelectMenu.Item>
              <MultiSelectMenu.Item value="candy">
                {'Candy'}
              </MultiSelectMenu.Item>
              <MultiSelectMenu.Item value="salad">
                {'Salad'}
              </MultiSelectMenu.Item>
              <MultiSelectMenu.NestedGroup>
                <MultiSelectMenu.NestedGroupLabel>
                  {'Fruits'}
                </MultiSelectMenu.NestedGroupLabel>
                <MultiSelectMenu.Item value="mango">
                  {'Mango'}
                </MultiSelectMenu.Item>
                <MultiSelectMenu.Item value="orange">
                  {'Orange'}
                </MultiSelectMenu.Item>
                <MultiSelectMenu.Item value="strawberry">
                  {'Strawberry'}
                </MultiSelectMenu.Item>
              </MultiSelectMenu.NestedGroup>
              <MultiSelectMenu.NestedGroup>
                <MultiSelectMenu.NestedGroupLabel>
                  {'Vegetables'}
                </MultiSelectMenu.NestedGroupLabel>
                <MultiSelectMenu.Item value="aubergine">
                  {'Aubergine'}
                </MultiSelectMenu.Item>
                <MultiSelectMenu.Item value="brocolli">
                  {'Brocolli'}
                </MultiSelectMenu.Item>
              </MultiSelectMenu.NestedGroup>
            </MultiSelectMenu.Content>
          </MultiSelectMenu.Root>
        </FormField.Root>
        <Box>
          <Button type="submit">{'Submit'}</Button>
        </Box>
      </Flex>
    </form>
  );
};
```

---

## Accessibility features

<ul>
  <li iconName="check">

Exposed to assistive technology as a [select-only combobox](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-select-only/) with a listbox popup using the [WAI ARIA Listbox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/).

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

Implements proper keyboard support and focus management practices.

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

Typeahead to allow selecting options by typing text, even without opening the listbox.

  </li>
</ul>

---

## API Reference

### MultiSelectMenu.Root

| Name               | Type                                | Default  | Description                                                                                                 | Required |
| ------------------ | ----------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------- | -------- |
| `value`            | `string[]`                          |          | The controlled value of the select. Use in conjunction with `onValueChange`.                                |          |
| `defaultValue`     | `string[]`                          |          | The value of the select when first rendered. Use when you do not need to control the selection state.       |          |
| `onValueChange`    | `(value: string[]) => void`         |          | Event handler called when the selection state changes.                                                      |          |
| `isOpen`           | `boolean`                           | `false`  | The controlled open state of the select menu. Use in conjunction with `onIsOpenChange`.                     |          |
| `defaultIsOpen`    | `boolean`                           |          | The open state of the select menu 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 select menu changes.                                        |          |
| `size`             | `"small" \| "medium"`               | `medium` | The size of the select menu.                                                                                |          |
| `isDisabled`       | `boolean`                           | `false`  | When `true`, the content of select menu can't be opened by user interaction.                                |          |
| `isRequired`       | `boolean`                           |          | When `true`, the select menu is marked as required.                                                         |          |
| `validationStatus` | `"error" \| "success" \| "warning"` |          | Styles the select menu to match the status.                                                                 |          |
| `name`             | `string`                            |          | Name attribute of the select element. Useful for form submission.                                           |          |

### MultiSelectMenu.Trigger

| 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.                                                |          |
| `withLabels`   | `boolean`                                                                                      | `false` | When `true`, the values inside the trigger are rendered as removable labels.                                                                                                                                                                                                                 |          |
| `startElement` | `React.ReactElement`                                                                           |         | `ReactElement` to render to the left of the triggers's children.                                                                                                                                                                                                                             |          |
| `endElement`   | `React.ReactElement`                                                                           |         | `ReactElement` to render to the right of the triggers's children.                                                                                                                                                                                                                            |          |
| `renderValue`  | `({ getSelectedItems: () => SelectMenuValueItem[]; isDisabled?: boolean }) => React.ReactNode` |         | Callback function used to override content rendering inside of the trigger. Cannot be used together with `withLabels` prop.                                                                                                                                                                  |          |

### MultiSelectMenu.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.                                                                                                                                                                            |          |

### MultiSelectMenu.Clear

| Name  | Type                                                      | Default  | Description                                                                                                                                                                                                                                                                                  | Required |
| ----- | --------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `as`  | `keyof JSX.IntrinsicElements \| React.ComponentType<any>` | `button` | 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.                                                |          |

### MultiSelectMenu.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 select menu item.                                                                                                                                                                                                                                                           | Yes      |
| `isDisabled` | `boolean`                                                 |         | When `true`, the item will be disabled, preventing the user from interacting with it.                                                                                                                                                                                                        |          |
| `textValue`  | `string`                                                  |         | By default the typeahead behavior will use the `textContent` of the `MultiSelectMenu.ItemText`. When the content is complex or non-textual, this property can be used to specify optional text for the typeahead search purposes.                                                            |          |
| `endElement` | `React.ReactElement`                                      |         | `ReactElement` to render to the right of the item's children.                                                                                                                                                                                                                                |          |

### MultiSelectMenu.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. |          |

### MultiSelectMenu.Group

| 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.                                                |          |

### MultiSelectMenu.Label

| 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.                                                |          |

### MultiSelectMenu.NestedGroup

| 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.                                                |          |

### MultiSelectMenu.NestedGroupLabel

| 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.                                                |          |
| `isDisabled` | `boolean`                                                 |         | When `true`, the item will be disabled, preventing the user from interacting with it.                                                                                                                                                                                                        |          |
| `endElement` | `React.ReactElement`                                      |         | `ReactElement` to render to the right of the item's children.                                                                                                                                                                                                                                |          |

### MultiSelectMenu.Separator

| 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.                                                |          |