Combobox

A Base UI (Angular) combobox is a searchable single-select with keyboard listbox behavior and optional create. Bind options and ngModel; for async search set filterMode to none and handle queryChange. The source is copied into your project so you own filtering and option templates.

When to use

Large or remote option lists where users type to filter.
Allow-create flows (tags, new records) without leaving the field.

When not to use

A short static list with no search — custom-select is simpler.
Free-text tags with chips — use tags-input.

Install with npx base-ui-cli add combobox.

freenew

Playground

Placeholder

Disabled

Allow create

HTML

<base-combobox
  [options]="people"
  [(ngModel)]="selected"
  placeholder="Search people…"
  [disabled]="false"
  [allowCreate]="false">
</base-combobox>

Default

Person

Selected: grace

HTML

Create option

Set [allowCreate]="true" to add the current query when it is not in the list.

HTML

Async search

Parent filters. Combobox shows a loading spinner while results catch up.

HTML

Empty, error, disabled

Async search already covers loading. Empty lists and validation copy belong next to the field.

Empty

Error

Pick someone from the list.

Directory lookup failed. Showing cached options.

Keyboard & accessibility

Role: Combobox with a listbox. aria-activedescendant tracks the highlighted option.
Focus: Focus stays in the input. The panel is not in the tab order.

Shortcuts

ArrowDownOpen and move to the next option
ArrowUpMove to the previous option
EnterSelect the highlighted option
EscClose without changing the value

Site-wide VPAT-style notes live on the accessibility report.

Installation

Run the following command to add this component to your project:

bash

npx base-ui-cli add combobox

API Reference

For AI agents

Copy a prompt with the registry name, CLI install, and import — or add the Base UI MCP server.

bash

npx -y base-ui-mcp

Base UI provides standalone components. Import the exact elements you want to use into your component.

typescript (Example)

// Install: npx base-ui-cli add combobox
// Paths are relative to aliases.components (default: src/app/components)
import { ComboboxComponent } from './combobox/combobox.component';

@Component({
  selector: 'app-your-component',
  imports: [
    ComboboxComponent
  ],
  template: `...`
})
export class YourComponent {}

API for combobox — generated from JSDoc in the library source.

API reference for combobox
API	Member	Type	Default	Description
`base-combobox`	`class`	`string`	`''`	Additional host classes.
`base-combobox`	`label`	`string`	`''`	Visible label above the field.
`base-combobox`	`placeholder`	`unknown`	`'Search…'`	Placeholder when nothing is selected.
`base-combobox`	`options`	`ComboboxOption[]`	`[]`	Options shown in the listbox.
`base-combobox`	`filterMode`	`'local' \| 'none'`	`'local'`	`local` filters by label; `none` shows `options` as-is (use with `queryChange` for async search).
`base-combobox`	`loading`	`boolean`	`false`	Shows a spinner in the panel (async search).
`base-combobox`	`allowCreate`	`boolean`	`false`	Allows creating the current query when it matches no option.
`base-combobox`	`emptyText`	`unknown`	`'No results'`	Empty-state copy when no options match.
`base-combobox`	`disabled`	`boolean`	`false`	Disables the field. Also set by Angular Forms via `setDisabledState`.
`base-combobox`	`(queryChange)`	`string`	—	Emits the typed query on every change.
`base-combobox`	`(create)`	`string`	—	Emits when the user creates a value that is not in `options`.
`base-combobox`	`(selectionChange)`	`string \| null`	—	Emits the selected option value.