Combobox

A Base UI (Angular) combobox is a searchable single-select with keyboard listbox behavior, optional create, and an optional baseComboboxOption template. Bind options and ngModel; for async search set filterMode to none and handle queryChange — or drive options from httpResource. Cookbook: http-resource.

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

<base-combobox [options]="people" [(ngModel)]="selected"></base-combobox>

TypeScript

import { Component } from '@angular/core';

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

@Component({
  selector: 'app-combobox-example',
  imports: [
    ComboboxComponent,
    ComboboxOptionDirective
  ],
  template: `...`
})
export class ComboboxExampleComponent {}

Install

bash

npx base-ui-cli add combobox

Option template

Project ng-template baseComboboxOption to render avatars, secondary copy, or badges in the listbox. Import ComboboxOptionDirective. Context: let-option, let-selected="selected", let-active="active", let-index="index".

Person

HTML

<base-combobox [options]="people" [(ngModel)]="selected">
  <ng-template baseComboboxOption let-option>
    <span>Ada Lovelace</span>
  </ng-template>
</base-combobox>

TypeScript

import { Component } from '@angular/core';

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

@Component({
  selector: 'app-combobox-example',
  imports: [
    ComboboxComponent,
    ComboboxOptionDirective
  ],
  template: `...`
})
export class ComboboxExampleComponent {}

Install

bash

npx base-ui-cli add combobox

Create option

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

HTML

<base-combobox [options]="items" [allowCreate]="true" (create)="onCreate($event)"></base-combobox>

TypeScript

import { Component } from '@angular/core';

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

@Component({
  selector: 'app-combobox-example',
  imports: [
    ComboboxComponent,
    ComboboxOptionDirective
  ],
  template: `...`
})
export class ComboboxExampleComponent {}

Install

bash

npx base-ui-cli add combobox

Async search

Parent filters. Combobox shows a loading spinner while results catch up. Pair queryChange with httpResource in the httpResource cookbook.

HTML

<base-combobox filterMode="none" [loading]="loading" [options]="results" (queryChange)="search($event)"></base-combobox>

TypeScript

import { Component } from '@angular/core';

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

@Component({
  selector: 'app-combobox-example',
  imports: [
    ComboboxComponent,
    ComboboxOptionDirective
  ],
  template: `...`
})
export class ComboboxExampleComponent {}

Install

bash

npx base-ui-cli add combobox

Empty, error, disabled

Async search already covers loading. Empty lists and validation copy belong next to the field. App-wide empty copy defaults to provideBaseUiI18n().

Empty

Error

Pick someone from the list.

Directory lookup failed. Showing cached options.

TypeScript

import { Component } from '@angular/core';

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

@Component({
  selector: 'app-combobox-example',
  imports: [
    ComboboxComponent,
    ComboboxOptionDirective
  ],
  template: `...`
})
export class ComboboxExampleComponent {}

Install

bash

npx base-ui-cli add combobox

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-ng-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 { ComboboxOptionContext, ComboboxOptionDirective } from './combobox/combobox-option.directive';
import { ComboboxComponent } from './combobox/combobox.component';

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

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

API reference for combobox
API	Member	Type	Default	Description
`ComboboxOptionContext`	`$implicit`	`ComboboxOption`	—	—
`ComboboxOptionContext`	`option`	`ComboboxOption`	—	—
`ComboboxOptionContext`	`selected`	`boolean`	—	—
`ComboboxOptionContext`	`active`	`boolean`	—	—
`ComboboxOptionContext`	`index`	`number`	—	—
`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. Override the row with `<ng-template baseComboboxOption>`.
`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`	`string`	—	Empty-state copy when no options match. When omitted, uses `provideBaseUiI18n().noResults`.
`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.
`[baseComboboxOption]`	`—`	`—`	—	Marks an `ng-template` as the option renderer for . When omitted, the listbox shows `option.label` and optional `option.description`.

Base UI (Angular) — base-ui.net — is a CLI-first Angular + Tailwind CSS component library with 215 components and blocks (125 free), delivered shadcn-style: npx base-ui-cli add copies the TypeScript/HTML source into your project, where you own and edit it. There is no npm library package. Not MUI Base UI (base-ui.com, React).