# ComboboxPopover
Package: @mantine/core
Import: import { ComboboxPopover } from '@mantine/core';
Description: Add combobox dropdown to any button element

## Usage

`ComboboxPopover` adds a dropdown with options to any element. It does not render an input,
pass your own target to `ComboboxPopover.Target`. The target must be a single element
or a component that accepts `ref`:

```tsx
import { useState } from 'react';
import { Button, ComboboxPopover } from '@mantine/core';

function Demo() {
  const [value, setValue] = useState<string | null>(null);

  return (
    <ComboboxPopover
      data={['React', 'Angular', 'Vue', 'Svelte']}
      value={value}
      onChange={setValue}
    >
      <ComboboxPopover.Target>
        <Button variant="default" miw={200}>{value || 'Select framework'}</Button>
      </ComboboxPopover.Target>
    </ComboboxPopover>
  );
}
```


## Data format

Pass an array of options to `data`:

* Use strings, numbers, or booleans when the value is also the label.
* Use an object like `{ value: 'ng', label: 'Angular' }` to display a different label. Add `disabled: true` to disable the option.
* To group options under a label, use `{ group: 'Frontend', items: ['React', 'Angular'] }`. Each group can contain primitive values or option objects.

## Searchable

Set `searchable` prop to add a search input to the dropdown:

```tsx
import { useState } from 'react';
import { Button, ComboboxPopover } from '@mantine/core';

function Demo() {
  const [value, setValue] = useState<string | null>(null);

  return (
    <ComboboxPopover
      data={['React', 'Angular', 'Vue', 'Svelte']}
      value={value}
      onChange={setValue}
      searchable
      nothingFoundMessage="Nothing found..."
    >
      <ComboboxPopover.Target>
        <Button variant="default" miw={200}>{value || 'Select framework'}</Button>
      </ComboboxPopover.Target>
    </ComboboxPopover>
  );
}
```


## Controlled search value

Use `searchValue` and `onSearchChange` props to control the search input value:

```tsx
import { useState } from 'react';
import { Button, ComboboxPopover, Text } from '@mantine/core';

function Demo() {
  const [value, setValue] = useState<string | null>(null);
  const [searchValue, setSearchValue] = useState('');

  return (
    <>
      <ComboboxPopover
        data={['React', 'Angular', 'Vue', 'Svelte']}
        value={value}
        onChange={setValue}
        searchable
        searchValue={searchValue}
        onSearchChange={setSearchValue}
      >
        <ComboboxPopover.Target>
          <Button variant="default" miw={200}>{value || 'Select framework'}</Button>
        </ComboboxPopover.Target>
      </ComboboxPopover>

      <Text mt="md" size="sm">
        Search value: <b>{searchValue || '(empty)'}</b>
      </Text>
      <Text size="sm">
        Selected value: <b>{value || '(none)'}</b>
      </Text>
    </>
  );
}
```


## Sort options

Use `filter` prop with `searchable` to customize filtering and sorting:

```tsx
import { useState } from 'react';
import { Button, ComboboxItem, ComboboxPopover, OptionsFilter } from '@mantine/core';

const optionsFilter: OptionsFilter = ({ options, search }) => {
  const filtered = (options as ComboboxItem[]).filter((option) =>
    option.label.toLowerCase().trim().includes(search.toLowerCase().trim())
  );

  filtered.sort((a, b) => a.label.localeCompare(b.label));
  return filtered;
};

function Demo() {
  const [value, setValue] = useState<string | null>(null);

  return (
    <ComboboxPopover
      data={['4 – React', '1 – Angular', '3 – Vue', '2 – Svelte']}
      value={value}
      onChange={setValue}
      searchable
      filter={optionsFilter}
      nothingFoundMessage="Nothing found..."
    >
      <ComboboxPopover.Target>
        <Button variant="default" miw={200}>{value || 'Select framework'}</Button>
      </ComboboxPopover.Target>
    </ComboboxPopover>
  );
}
```


## Limit options

Use `limit` prop with `searchable` to limit the number of options displayed at a time:

```tsx
import { useState } from 'react';
import { Button, ComboboxPopover } from '@mantine/core';

const largeData = Array(1000)
  .fill(0)
  .map((_, index) => `Option ${index}`);

function Demo() {
  const [value, setValue] = useState<string | null>(null);

  return (
    <ComboboxPopover
      data={largeData}
      value={value}
      onChange={setValue}
      searchable
      limit={5}
      nothingFoundMessage="Nothing found..."
    >
      <ComboboxPopover.Target>
        <Button variant="default" miw={200}>{value || 'Select option'}</Button>
      </ComboboxPopover.Target>
    </ComboboxPopover>
  );
}
```


## Multiple selection

Set `multiple` prop to allow selecting multiple values, `value` becomes an array of strings:

```tsx
import { useState } from 'react';
import { Button, ComboboxPopover } from '@mantine/core';

function Demo() {
  const [value, setValue] = useState<string[]>([]);

  return (
    <ComboboxPopover
      data={['React', 'Angular', 'Vue', 'Svelte']}
      value={value}
      onChange={setValue}
      multiple
    >
      <ComboboxPopover.Target>
        <Button variant="default" miw={200}>
          {value.length > 0 ? value.join(', ') : 'Select frameworks'}
        </Button>
      </ComboboxPopover.Target>
    </ComboboxPopover>
  );
}
```


## Check icon

```tsx
import { Button, ComboboxPopover } from '@mantine/core';

function Demo() {
  return (
    <ComboboxPopover
       withCheckIcon={true} withAlignedLabels={false} checkIconPosition="left"
      data={['React', 'Angular', 'Svelte', 'Vue']}
      dropdownOpened
      defaultValue="React"
      comboboxProps={{ position: 'bottom', middlewares: { flip: false } }}
    >
      <ComboboxPopover.Target>
        <Button variant="default" miw={200} mb={150}>Select framework</Button>
      </ComboboxPopover.Target>
    </ComboboxPopover>
  );
}
```


## Allow deselect

By default, clicking the selected option again deselects it. Set `allowDeselect={false}` to prevent this:

```tsx
import { useState } from 'react';
import { Button, ComboboxPopover, Stack } from '@mantine/core';

function Demo() {
  const [value1, setValue1] = useState<string | null>('React');
  const [value2, setValue2] = useState<string | null>('React');

  return (
    <Stack>
      <ComboboxPopover
        data={['React', 'Angular', 'Vue', 'Svelte']}
        value={value1}
        onChange={setValue1}
        allowDeselect={false}
      >
        <ComboboxPopover.Target>
          <Button variant="default" miw={200}>
            {value1 || 'Cannot deselect'}
          </Button>
        </ComboboxPopover.Target>
      </ComboboxPopover>

      <ComboboxPopover
        data={['React', 'Angular', 'Vue', 'Svelte']}
        value={value2}
        onChange={setValue2}
        allowDeselect
      >
        <ComboboxPopover.Target>
          <Button variant="default" miw={200}>
            {value2 || 'Can deselect (default)'}
          </Button>
        </ComboboxPopover.Target>
      </ComboboxPopover>
    </Stack>
  );
}
```


## Nothing found message

Set `nothingFoundMessage` prop to display a message when no options are available:

```tsx
import { Button, ComboboxPopover } from '@mantine/core';

function Demo() {
  return (
    <ComboboxPopover
      data={[]}
      nothingFoundMessage="No options available"
    >
      <ComboboxPopover.Target>
        <Button variant="default" miw={200}>Open dropdown</Button>
      </ComboboxPopover.Target>
    </ComboboxPopover>
  );
}
```


## Disabled options

```tsx
import { Button, ComboboxPopover } from '@mantine/core';

function Demo() {
  return (
    <ComboboxPopover
      data={[
        { value: 'react', label: 'React' },
        { value: 'ng', label: 'Angular' },
        { value: 'vue', label: 'Vue', disabled: true },
        { value: 'svelte', label: 'Svelte', disabled: true },
      ]}
    >
      <ComboboxPopover.Target>
        <Button variant="default" miw={200}>Select framework</Button>
      </ComboboxPopover.Target>
    </ComboboxPopover>
  );
}
```


## Groups

```tsx
import { useState } from 'react';
import { Button, ComboboxPopover } from '@mantine/core';

function Demo() {
  const [value, setValue] = useState<string | null>(null);

  return (
    <ComboboxPopover
      data={[
        { group: 'Frontend', items: ['React', 'Angular', 'Vue'] },
        { group: 'Backend', items: ['Node.js', 'Django', 'Rails'] },
      ]}
      value={value}
      onChange={setValue}
    >
      <ComboboxPopover.Target>
        <Button variant="default" miw={200}>{value || 'Select technology'}</Button>
      </ComboboxPopover.Target>
    </ComboboxPopover>
  );
}
```


## Render option

Use `renderOption` prop to customize option rendering:

```tsx
import { useState } from 'react';
import {
  CheckIcon,
  TextAlignCenterIcon,
  TextAlignJustifyIcon,
  TextAlignLeftIcon,
  TextAlignRightIcon,
} from '@phosphor-icons/react';
import { Button, ComboboxPopover, ComboboxPopoverProps, Group } from '@mantine/core';

const iconProps = {
  color: 'currentColor',
  opacity: 0.6,
  size: 18,
};

const icons: Record<string, React.ReactNode> = {
  left: <TextAlignLeftIcon {...iconProps} />,
  center: <TextAlignCenterIcon {...iconProps} />,
  right: <TextAlignRightIcon {...iconProps} />,
  justify: <TextAlignJustifyIcon {...iconProps} />,
};

const renderSelectOption: ComboboxPopoverProps['renderOption'] = ({ option, checked }) => (
  <Group flex="1" gap="xs">
    {icons[option.value]}
    {option.label}
    {checked && <CheckIcon style={{ marginInlineStart: 'auto' }} {...iconProps} />}
  </Group>
);

function Demo() {
  const [value, setValue] = useState<string | null>(null);

  return (
    <ComboboxPopover
      data={[
        { value: 'left', label: 'Left' },
        { value: 'center', label: 'Center' },
        { value: 'right', label: 'Right' },
        { value: 'justify', label: 'Justify' },
      ]}
      value={value}
      onChange={setValue}
      renderOption={renderSelectOption}
    >
      <ComboboxPopover.Target>
        <Button variant="default" miw={200}>{value || 'Select alignment'}</Button>
      </ComboboxPopover.Target>
    </ComboboxPopover>
  );
}
```


## Virtualized dropdown

Use `virtualizer` to render only the visible options. Open the popover and search for an option by number:

```tsx
import { useState } from 'react';
import { Button, ComboboxPopover } from '@mantine/core';
import { VirtualList } from './VirtualList';

${dataCode}

function Demo() {
  const [value, setValue] = useState<string | null>(null);

  return (
    <ComboboxPopover data={data} value={value} onChange={setValue} searchable virtualizer={VirtualList}>
      <ComboboxPopover.Target>
        <Button variant="default" miw={200}>{value || 'Choose an option'}</Button>
      </ComboboxPopover.Target>
    </ComboboxPopover>
  );
}
```


## Large data sets

The dropdown is scrollable, use `maxDropdownHeight` to set its maximum height:

```tsx
import { Button, ComboboxPopover } from '@mantine/core';

const data = Array(50)
  .fill(0)
  .map((_, index) => `Option ${index}`);

function Demo() {
  return (
    <ComboboxPopover data={data} maxDropdownHeight={200}>
      <ComboboxPopover.Target>
        <Button variant="default" miw={200}>Select option</Button>
      </ComboboxPopover.Target>
    </ComboboxPopover>
  );
}
```


## Control dropdown opened state

Use `dropdownOpened`, `onDropdownOpen` and `onDropdownClose` props to control the dropdown state:

```tsx
import { Button, ComboboxPopover, Group } from '@mantine/core';
import { useDisclosure } from '@mantine/hooks';

function Demo() {
  const [dropdownOpened, { toggle }] = useDisclosure();

  return (
    <Group>
      <Button onClick={toggle}>Toggle dropdown</Button>
      <ComboboxPopover
        data={['React', 'Angular', 'Vue', 'Svelte']}
        dropdownOpened={dropdownOpened}
      >
        <ComboboxPopover.Target>
          <Button variant="default" miw={200}>Select framework</Button>
        </ComboboxPopover.Target>
      </ComboboxPopover>
    </Group>
  );
}
```


## Dropdown position

```tsx
import { Button, ComboboxPopover } from '@mantine/core';

function Demo() {
  return (
    <ComboboxPopover
      data={['React', 'Angular', 'Vue', 'Svelte']}
      comboboxProps={{ position: 'top', middlewares: { flip: false, shift: false } }}
    >
      <ComboboxPopover.Target>
        <Button variant="default" miw={200}>Open dropdown above</Button>
      </ComboboxPopover.Target>
    </ComboboxPopover>
  );
}
```


## Dropdown width

By default, the dropdown width matches the target. Set a custom width with `comboboxProps`:

```tsx
import { Button, ComboboxPopover } from '@mantine/core';

function Demo() {
  return (
    <ComboboxPopover
      data={['React', 'Angular', 'Vue', 'Svelte']}
      comboboxProps={{ width: 250, position: 'bottom-start' }}
    >
      <ComboboxPopover.Target>
        <Button variant="default" miw={200}>Select framework</Button>
      </ComboboxPopover.Target>
    </ComboboxPopover>
  );
}
```


## Dropdown animation

```tsx
import { Button, ComboboxPopover } from '@mantine/core';

function Demo() {
  return (
    <ComboboxPopover
      data={['React', 'Angular', 'Vue', 'Svelte']}
      comboboxProps={{ transitionProps: { transition: 'pop', duration: 200 } }}
    >
      <ComboboxPopover.Target>
        <Button variant="default" miw={200}>With animation</Button>
      </ComboboxPopover.Target>
    </ComboboxPopover>
  );
}
```


## Form submission

Set `name` to include the selection in native form submission.


#### Props

**ComboboxPopover props**

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| allowDeselect | boolean | true | Allows deselecting the selected option by clicking it (only for single mode) |
| aria-label | string | - | Accessible name of the options list, also applied to the target element. If not set, the list is labelled by the target element |
| checkIconPosition | "left" \| "right" | 'left' | Position of the check icon relative to the option label |
| children | React.ReactNode | - | Content of the component |
| comboboxProps | ComboboxProps | - | Props passed down to Combobox component |
| data | ComboboxData<Value> | - | Data used to generate options |
| defaultDropdownOpened | boolean | - | Uncontrolled dropdown initial opened state |
| defaultSearchValue | string | - | Default search value |
| defaultValue | Primitive \| Value[] \| null | - | Uncontrolled component default value |
| dropdownOpened | boolean | - | Controlled dropdown opened state |
| filter | OptionsFilter<Value> | - | Function based on which items are filtered and sorted |
| form | string | - | Hidden input form for form submission |
| hiddenInputProps | React.ComponentProps<"input"> | - | Props passed down to the hidden input |
| hiddenInputValuesDivider | string | ',' | Divider used to separate values in the hidden input value attribute |
| limit | number | Infinity | Maximum number of options displayed at a time |
| maxDropdownHeight | string \| number | 220 | max-height of the dropdown |
| multiple | boolean | - | If set, multiple items can be selected at the same time |
| name | string | - | Hidden input name for form submission |
| nothingFoundMessage | React.ReactNode | - | Message displayed when no options match the search query or when there is no data |
| onChange | (value: ComboboxPopoverValue<Multiple, Value>) => void | - | Called when value changes |
| onDropdownClose | () => void | - | Called when dropdown closes |
| onDropdownOpen | () => void | - | Called when dropdown opens |
| onOptionSubmit | (value: Value) => void | - | Called when option is submitted from dropdown with mouse click or Enter key |
| onSearchChange | (value: string) => void | - | Called when search changes |
| renderOption | (item: ComboboxLikeRenderOptionInput<ComboboxItem<string>>) => ReactNode | - | A function to render content of the option, replaces the default content of the option |
| scrollAreaProps | ScrollAreaProps | - | Props passed down to the underlying ScrollArea component in the dropdown |
| scrollBehavior | ScrollBehavior | 'instant' | `behavior` passed down to `element.scrollIntoView` when options are scrolled into view with keyboard navigation |
| searchValue | string | - | Controlled search value |
| searchable | boolean | false | Allows searching through options |
| selectFirstOptionOnDropdownOpen | boolean | false | If set, the first option is selected when dropdown opens |
| value | Primitive \| Value[] \| null | - | Controlled component value |
| virtualizer | ComponentType<ComboboxVirtualizerProps> | - | Component that renders visible rows and manages scrolling in place of the dropdown ScrollArea |
| withAlignedLabels | boolean | false | Aligns unchecked labels with the checked one |
| withCheckIcon | boolean | true | Displays check icon near the selected option label |
| withScrollArea | boolean | true | Determines whether the options should be wrapped with ScrollArea.AutoSize |


#### Styles API

ComboboxPopover component supports Styles API. With Styles API, you can customize styles of any inner element. Follow the documentation to learn how to use CSS modules, CSS variables and inline styles to get full control over component styles.

**ComboboxPopover selectors**

| Selector | Static selector | Description |
|----------|----------------|-------------|
| search | .mantine-ComboboxPopover-search | Search input, displayed only when `searchable` prop is set |

**ComboboxPopover data attributes**

| Selector | Attribute | Condition | Value |
|----------|-----------|-----------|-------|
| option | data-checked | Option is selected | - |
| option | data-combobox-active | Option is selected | - |
| option | data-combobox-disabled | Option is disabled | - |
| option | data-reverse | `checkIconPosition` is `right` | - |
| dropdown | data-hidden | There are no options to display and `nothingFoundMessage` is not set | - |
