> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognite.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Cognite Data Fusion (CDF) is an industrial DataOps platform. Prefer English docs unless the user asks for another locale.
> Follow /_llms/ index links recursively until you reach page URLs ending in .md. Fetch those Markdown twins instead of HTML.
> For REST APIs, default to calendar version 20230101 (stable). Use 20230101-beta or 20230101-alpha only if the user is on a preview API. Cite paths under /api-reference/concepts/<version>/ and the Cdf-Version header. Prefer the Python SDK (cognite-sdk) unless the user is in JavaScript/TypeScript.
> Start here by task: platform overview /cdf/index.md; data modeling /cdf/dm/index.md; data integration /cdf/integration/index.md; access /cdf/access/index.md; CDF Toolkit /cdf/deploy/cdf_toolkit/index.md; REST quickstart /dev/quickstart.md; Python SDK /dev/sdks/python/index.md; Atlas AI /cdf/atlas_ai/concepts/index.md; Flows apps /cdf/flows/index.md; Aura UI /cdf/aura/index.md; MCP and IDE setup /dev/guides/ide_ai_integration.md.
> For implementation work, also load /skill.md.

# Combobox

> A searchable select input that filters a list of options as the user types. Supports single and multi-select, and optionally allows users to add new items that aren't in the existing list.

<Badge color="blue">v1.0.0</Badge> | [View in Storybook](https://master--695bb4b1b8041ae09768950a.chromatic.com/?path=/docs/primitives-combobox--docs)

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-combobox--basic" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-combobox--basic&viewMode=story&globals=theme:light" title="Combobox basic story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>

## When to use

* More than \~12 options, where typing to filter is faster than scrolling.
* The user knows roughly what they're looking for (e.g. selecting a country, an asset name, a tag)
* Forms where users need to search and select from a predefined list.
* When users need to add new options that don't exist in the list yet.

## When to use something else

* Fewer than \~12 options: use [Select](/cdf/aura/primitives/select), [Radio](/cdf/aura/primitives/radio), or [Checkbox](/cdf/aura/primitives/checkbox) depending on context.
* The user is unfamiliar with the available options and wouldn't know what to type: a visible list is less intimidating.
* Very large datasets where filtering may cause lag: consider a [Data grid](/cdf/aura/primitives/data-grid) with toolbar filtering instead.
* Free text input with no list to select from: use [Input](/cdf/aura/primitives/input) or [Textarea](/cdf/aura/primitives/textarea).

## Dos and don'ts

* **Do** group related options if the list spans multiple categories.
* **Do** use clearable Badges when a user can select multiple options as this allows for quick and easy clearing.
* **Do** left align with other input fields when used in a form.
* **Don't** use it for simple yes/no or small option sets: the search affordance implies more options than are there.
* **Don't** use default selections as users may not thoroughly check the default.
* **Don't** make the menu smaller than the Combobox input field.

## Behavior

* **Single-select:** the menu closes immediately on selection.
* **Multi-select:** the menu stays open until the user clicks outside, presses Escape, or presses Enter.
* **Searching:** users can search for an item by typing in the input field. As the user types, the list items should filter out if they don't match the searched content. Searched strings should be highlighted in the list to help the user easily identify what they are looking for.
* **Adding items:** users can add an item by typing the item in the input field and hitting Enter or Return on the keyboard or the "Add + \[label item]" button at the bottom of the list. Adding the item automatically selects it.
* **Clearing items:** there are four ways in which content can be cleared from the input area:
  * The user can deselect menu items to remove them from the input area.
  * The user can input their cursor anywhere in the input and hit Delete or backspace on their keyboard. This method works for both strings and Filter chips.
  * The user can clear individual Filter chips but clicking the "X" icon button inside the chip.
  * Combobox can optionally display a Clear all button to the right of the text, but left of the chevron, allowing the user to quickly clear all content within the field. Clear all buttons are not displayed until after a user has input content.

## Combobox menu

Combobox menus display a checkmark, or toggle, to the right of the menu item, instead of on the left like traditional Context and Dropdown menus. This is because scanning the list is easier when the checkmark is on the right. Therefore it is recommended to avoid leading content like an icon or Badge on the left side of the menu item. Badges should be placed on the right side of the menu item.

## Often used with

[Label](/cdf/aura/primitives/label), [Helper text](/cdf/aura/primitives/helper-text); optional [Badge](/cdf/aura/primitives/badge) on menu rows; same field anatomy as [Input](/cdf/aura/primitives/input) (leading/trailing slots) when used in forms.

## Accessibility

* Explicit labeling: Pass an `aria-label` or `aria-labelledby` to the PopoverTrigger button, or associate it with an external `<Label>` element using matching `htmlFor` and `id` attributes.
* Form validation and error states: Apply `aria-invalid="true"` to the trigger button when validation fails, and link error messages via `aria-describedby="error-message-id"`.
* Custom option content: If rendering icons, status badges, or subtext inside a `<CommandItem>`, wrap hidden contextual details in `<span className="sr-only">` so screen readers hear more than just visual fragments.
* Trigger text and placeholders: Ensure the trigger button displays meaningful visual text when an item is selected, rather than a visual-only icon or blank state.
* Custom styling and focus rings: If overriding default Tailwind classes, preserve visible focus rings (`focus-visible:ring-2`) on the trigger and maintain a minimum 4.5:1 text/icon contrast ratio across hovered, selected, and disabled option states.

## Visual examples

The examples below are interactive and follow the doc site's theming: light mode when the docs site is in light mode, and dark mode when you switch the docs site to dark mode.

### Composed

Use the composed Combobox when the field needs a full form layout—label, helper text, and input slots—so search-and-select behaves like other form controls in your application.

<Frame>
  <iframe className="aura-storybook-embed w-full rounded-lg border border-zinc-950/10 dark:border-white/10" data-story-id="primitives-combobox--composed" src="https://master--695bb4b1b8041ae09768950a.chromatic.com/iframe.html?id=primitives-combobox--composed&viewMode=story&globals=theme:light" title="Combobox composed story" loading="lazy" style={{ height: "360px", display: "block", width: "100%" }} />
</Frame>