# @leafygreen-ui/combobox

> leafyGreen UI Kit Combobox

Latest version **12.5.2** (published 2026-10-02) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @leafygreen-ui/combobox
pnpm add @leafygreen-ui/combobox
yarn add @leafygreen-ui/combobox
bun add @leafygreen-ui/combobox
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 12.5.2 |
| Published | 2026-10-02 |
| First published | 2022-01-19 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 16 |
| Unpacked size | 767.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 274 |
| Maintainers | thesonofthomp, shaneeza, stephl3, aitchpgm, hnevins, _tsck |

## Links

- npm: https://www.npmjs.com/package/@leafygreen-ui/combobox
- Repository: https://github.com/mongodb/leafygreen-ui
- Homepage: https://github.com/mongodb/leafygreen-ui/tree/main/packages/combobox
- Issues: https://jira.mongodb.org/projects/PD/summary
- npm.io page: https://npm.io/package/@leafygreen-ui/combobox

## Dependencies (16)

- [chalk](https://npm.io/package/chalk.md) ^4.1.2
- [lodash](https://npm.io/package/lodash.md) ^4.17.21
- [polished](https://npm.io/package/polished.md) ^4.2.2
- [@leafygreen-ui/lib](https://npm.io/package/@leafygreen-ui/lib.md) ^15.7.1
- [@leafygreen-ui/chip](https://npm.io/package/@leafygreen-ui/chip.md) ^4.2.2
- [@leafygreen-ui/icon](https://npm.io/package/@leafygreen-ui/icon.md) ^14.9.1
- [@leafygreen-ui/hooks](https://npm.io/package/@leafygreen-ui/hooks.md) ^9.3.2
- [@leafygreen-ui/tokens](https://npm.io/package/@leafygreen-ui/tokens.md) ^4.2.3
- [@leafygreen-ui/emotion](https://npm.io/package/@leafygreen-ui/emotion.md) ^5.2.1
- [@leafygreen-ui/palette](https://npm.io/package/@leafygreen-ui/palette.md) ^5.0.3
- [@leafygreen-ui/popover](https://npm.io/package/@leafygreen-ui/popover.md) ^14.3.3
- [@leafygreen-ui/checkbox](https://npm.io/package/@leafygreen-ui/checkbox.md) ^18.1.6
- [@leafygreen-ui/form-field](https://npm.io/package/@leafygreen-ui/form-field.md) ^4.0.10
- [@leafygreen-ui/typography](https://npm.io/package/@leafygreen-ui/typography.md) ^22.2.5
- [@leafygreen-ui/icon-button](https://npm.io/package/@leafygreen-ui/icon-button.md) ^17.1.6
- [@leafygreen-ui/input-option](https://npm.io/package/@leafygreen-ui/input-option.md) ^4.1.6

## Recent versions

- 12.5.2 (latest) — 2026-10-02
- 12.5.1 — 2026-03-12
- 12.5.0 — 2026-02-11
- 12.4.2 — 2026-02-03
- 12.4.1 — 2026-01-21
- 12.4.0 — 2026-01-20
- 12.3.0 — 2025-11-24
- 12.2.1 — 2025-11-13
- 12.2.0 — 2025-11-06
- 12.1.0 — 2025-10-31
- 12.0.8 — 2025-10-21
- 12.0.7 — 2025-09-25
- 12.0.6 — 2025-09-10
- 12.0.5 — 2025-09-03
- 12.0.4 — 2025-07-28
- … 104 more at https://npm.io/package/@leafygreen-ui/combobox/versions

## README

# Combobox

![npm (scoped)](https://img.shields.io/npm/v/@leafygreen-ui/combobox.svg)

#### [View on MongoDB.design](https://www.mongodb.design/component/combobox/live-example/)

## Installation

### PNPM

```shell
pnpm add @leafygreen-ui/combobox
```

### Yarn

```shell
yarn add @leafygreen-ui/combobox
```

### NPM

```shell
npm install @leafygreen-ui/combobox
```

## Example

```js
import { Combobox, ComboboxOption } from '@leafygreen-ui/combobox';

<Combobox
  label="Choose a fruit"
  description="Please pick one"
  placeholder="Select fruit"
>
  <ComboboxOption value="apple" />
  <ComboboxOption value="banana" />
  <ComboboxOption value="carrot" />
  <ComboboxOption value="dragonfruit" />
  <ComboboxGroup label="Peppers">
    <ComboboxOption value="cayenne" />
    <ComboboxOption value="habanero" />
    <ComboboxOption value="jalapeno" displayName="Jalapeño" />
  </ComboboxGroup>
</Combobox>;
```

## Properties

| Prop                     | Type                                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Default                           |
| ------------------------ | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------ |
| `children`               | `<ComboboxOption>`, `<ComboboxGroup>`         | Define the Combobox Options by passing children                                                                                                                                                                                                                                                                                                                                                                                                                     |                                   |
| `multiselect`            | `boolean`                                     | Defines whether a user can select multiple options, or only a single option. When using TypeScript, `multiselect` affects the valid values of `initialValue`, `value`, and `onChange`                                                                                                                                                                                                                                                                               | `false`                           |
| `initialValue`           | `Array<string>`, `string`                     | The initial selection. Must be a string (or array of strings) that matches the `value` prop of a `ComboboxOption`. Changing the `initialValue` after initial render will not change the selection.                                                                                                                                                                                                                                                                  |                                   |
| `value`                  | `Array<string>`, `string`                     | The controlled value of the Combobox. Must be a string (or array of strings) that matches the `value` prop of a `ComboboxOption`. Changing `value` after initial render _will_ affect the selection. `value` will always take precedence over `initialValue` if both are provided.                                                                                                                                                                                  |                                   |
| `onChange`               | `(Array<string>) => void`, `(string) => void` | A callback called when the selection changes. Callback recieves a single argument that is the new selection, either string, or string array                                                                                                                                                                                                                                                                                                                         |                                   |
| `overflow`               | `'expand-y'`, `'expand-x'`, `'scroll-x'`      | Defines the overflow behavior of a multiselect combobox. **expand-y**: Combobox has fixed width, and additional selections will cause the element to grow in the block direction. **expand-x**: Combobox has fixed height, and additional selections will cause the elemenet to grow in the inline direction. **scroll-x**: Combobox has fixed height and width, and additional selections will cause the element to be scrollable in the x (horizontal) direction. | `'expand-y'`                      |
| `label`                  | `string`                                      | An accessible label for the input, rendered in a `<label>` to the DOM                                                                                                                                                                                                                                                                                                                                                                                               |                                   |
| `aria-label`             | `string`                                      | An accessible label for the input, used only for screen-readers                                                                                                                                                                                                                                                                                                                                                                                                     |                                   |
| `description`            | `React.ReactNode`                             | A description for the input                                                                                                                                                                                                                                                                                                                                                                                                                                         |                                   |
| `placeholder`            | `string`                                      | A placeholder for the input element. Uses the native `placeholder` attribute.                                                                                                                                                                                                                                                                                                                                                                                       | 'Select'                          |
| `disabled`               | `boolean`                                     | Disables all interaction with the component                                                                                                                                                                                                                                                                                                                                                                                                                         | false                             |
| `size`                   | `'default'`                                   | Defines the visual size of the component                                                                                                                                                                                                                                                                                                                                                                                                                            | 'default'                         |
| `darkMode`               | `boolean`                                     | Toggles dark mode                                                                                                                                                                                                                                                                                                                                                                                                                                                   | false                             |
| `state`                  | `'error'`, `'none'`                           | The error state of the component. Defines whether the error message is displayed.                                                                                                                                                                                                                                                                                                                                                                                   | 'none'                            |
| `errorMessage`           | `string`                                      | The message shown below the input when `state` is `error`                                                                                                                                                                                                                                                                                                                                                                                                           | 'This input needs your attention' |
| `successMessage`         | `string`                                      | The message shown below the input when `state` is `valid`                                                                                                                                                                                                                                                                                                                                                                                                           | 'Success'                         |
| `onFilter`               | `(value: string) => void`                     | A callback called when the search input changes. Recieves a single argument that is the current input value. Use this callback to set `searchState` and/or `filteredOptions` appropriately                                                                                                                                                                                                                                                                          |                                   |
| `searchState`            | `'unset'`, `'error'`, `'loading'`             | The state of search results. Toggles search messages within the menu.                                                                                                                                                                                                                                                                                                                                                                                               | 'unset'                           |
| `searchErrorMessage`     | `string`                                      | A message shown within the menu when `searchState` is `error`                                                                                                                                                                                                                                                                                                                                                                                                       | 'Could not get results!'          |
| `searchLoadingMessage`   | `string`                                      | A message shown within the menu when `searchState` is `loading`                                                                                                                                                                                                                                                                                                                                                                                                     | 'Loading results...'              |
| `searchEmptyMessage`     | `string`                                      | A message shown within the menu when there are no options passed in as children, or `filteredOptions` is an empty array                                                                                                                                                                                                                                                                                                                                             | 'No results found'                |
| `clearable`              | `boolean`                                     | Defines whether the Clear button appears to the right of the input                                                                                                                                                                                                                                                                                                                                                                                                  |                                   |
| `onClear`                | `(e: MouseEvent) => void`                     | A callback fired when the Clear button is pressed. Fired _after_ `onChange`, and _before_ `onFilter`                                                                                                                                                                                                                                                                                                                                                                |                                   |
| `filteredOptions`        | `Array<string>`, `null`                       | An array used to define which options are displayed. Do not remove Options from the JSX children, as this will affect the selected options                                                                                                                                                                                                                                                                                                                          |                                   |
| `chipTruncationLocation` | `'start'`, `'middle'`, `'end'`, `'none'`      | Defines where the ellipses appear in a Chip when the length exceeds the `chipCharacterLimit`                                                                                                                                                                                                                                                                                                                                                                        | 'none'                            |
| `chipCharacterLimit`     | `number`                                      | Defined the character limit of a multiselect Chip before they start truncating. Note: the three ellipses dots are included in the character limit.                                                                                                                                                                                                                                                                                                                  | 12                                |
| `className`              | `string`                                      | The className passed to the root element of the component.                                                                                                                                                                                                                                                                                                                                                                                                          |                                   |
| `renderMode`             | `'inline'` \| `'portal'` \| `'top-layer'`     | Options to render the popover element <br> \* [deprecated] `'inline'` will render the popover element inline in the DOM where it's written <br> \* [deprecated] `'portal'` will render the popover element in a new div appended to the body. Alternatively, can be portaled into a provided `portalContainer` <br> \* `'top-layer'` will render the popover element in the top layer                                                                               | `'top-layer'`                     | `true` |
| `portalContainer`        | `HTMLElement` \| `null`                       | Sets the container used for the popover's portal.                                                                                                                                                                                                                                                                                                                                                                                                                   |                                   |
| `scrollContainer`        | `HTMLElement` \| `null`                       | If the popover portal has a scrollable ancestor other than the window, this prop allows passing a reference to that element to allow the portal to position properly.                                                                                                                                                                                                                                                                                               |                                   |
| `portalClassName`        | `string`                                      | Passes the given className to the popover's portal container if the default portal container is being used.                                                                                                                                                                                                                                                                                                                                                         |                                   |
| `popoverZIndex`          | `number`                                      | Sets the z-index CSS property for the popover.                                                                                                                                                                                                                                                                                                                                                                                                                      |                                   |

# ComboboxOption

## Props

| Prop            | Type                                                                         | Description                                                                                                                                                                   | Default |
| --------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `value`         | `string`                                                                     | The internal value of the option. Used as the identifier in Combobox `initialValue`, `value` and `filteredOptions`. When undefined, this is set to `_.kebabCase(displayName)` |         |
| `displayName`   | `string`                                                                     | The display value of the option. Used as the rendered string within the menu and chips. When undefined, this is set to `value`                                                |         |
| `customContent` | `ReactNode`                                                                  | Optional custom content to render for the option. When provided, this ReactNode will be rendered in the option menu                                                           |         |
| `glyph`         | `<Icon/>`                                                                    | The icon to display to the left of the option in the menu.                                                                                                                    |         |
| `className`     | `string`                                                                     | The className passed to the root element of the component.                                                                                                                    |         |
| `description`   | `string`                                                                     | Optional descriptive text under the displayName.                                                                                                                              |         |
| `onClick`       | `(event: React.SyntheticEvent<HTMLLIElement, Event>, value: string) => void` | Callback fired when an option is clicked. Returns the event and the option value.                                                                                             |         |

# ComboboxGroup

## Props

| Prop        | Type               | Description                                                | Default |
| ----------- | ------------------ | ---------------------------------------------------------- | ------- |
| `label`     | `string`           | Label for the group of options                             |         |
| `children`  | `<ComboboxOption>` | Options in the group                                       |         |
| `className` | `string`           | The className passed to the root element of the component. |         |

---
_Source: https://npm.io/package/@leafygreen-ui/combobox · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._