Combobox

The Combobox primitive is a combination of a dropdown and an input field. It allows users to select from a list of options while filtering the list based on their input.

Import

Import the Combobox primitives from ng-primitives/combobox.

import {
  NgpCombobox,
  NgpComboboxButton,
  NgpComboboxDropdown,
  NgpComboboxInput,
  NgpComboboxOption,
  NgpComboboxPortal,
} from 'ng-primitives/combobox';

Usage

Assemble the combobox directives in your template.

<div ngpCombobox>
  <input ngpComboboxInput />
  <button ngpComboboxButton>▼</button>
  <div ngpComboboxDropdown>
    @for (option of options; track option) {
    <div ngpComboboxOption [ngpComboboxOptionValue]="option">{{ option }}</div>
    }
  </div>
</div>

Without Input Field

You can also create a combobox without an input field, which is useful for select-like behavior with keyboard navigation:

<div ngpCombobox>
  <button ngpComboboxButton>{{ selectedOption || 'Select an option' }} ▼</button>
  <div ngpComboboxDropdown>
    @for (option of options; track option) {
    <div ngpComboboxOption [ngpComboboxOptionValue]="option">{{ option }}</div>
    }
  </div>
</div>

When no input is present, the combobox element itself becomes focusable and supports full keyboard navigation.

Reusable Component

Create a reusable component that uses the NgpCombobox directive.

Examples

Button-only Combobox

This example demonstrates a combobox without an input field. The combobox element itself becomes focusable.

Multiple Selection with chips

Select All Functionality

The combobox supports a "Select All" option for multiple selection mode, allowing users to select or deselect all options at once.

Select All Features

• Toggle All: Click to select all options if not all are selected, or deselect all if all are selected
• Visual State: The "Select All" option shows as selected when all individual options are selected
• Filtering Support: When options are filtered, "Select All" only affects currently visible options
• Keyboard Navigation: Full keyboard support with Arrow keys and Enter
• Multiple Mode Only: Automatically disabled in single selection mode

To implement Select All, use the special value 'all' for your Select All option:

<div ngpComboboxOptionValue="all" ngpComboboxOption>Select All</div>

Virtualized Large Lists

When dealing with large datasets (thousands of items), you can use TanStack Virtual or other virtualization libraries to efficiently render only the visible options, improving performance:

Custom Option Behavior

Options without a value do not perform any selection by default. You can use this to implement custom behavior, such as clearing the selection. These options are still included in keyboard navigation.

Schematics

Generate a reusable combobox component using the Angular CLI.

ng g ng-primitives:primitive combobox

Options

• path: The path at which to create the component file.
• prefix: The prefix to apply to the generated component selector.
• component-suffix: The suffix to apply to the generated component class name.
• file-suffix: The suffix to apply to the generated component file name. Defaults to component.
• example-styles: Whether to include example styles in the generated component file. Defaults to true.

API Reference

The following directives are available to import from the ng-primitives/combobox package:

NgpCombobox

The main container for the combobox.

Focus Management

When no ngpComboboxInput is present, the combobox element itself receives:

• tabindex="0" to make it focusable via keyboard navigation
• tabindex="-1" when disabled or when an input is present
• Full keyboard navigation support

NgpComboboxButton

The button that toggles the combobox dropdown.

NgpComboboxDropdown

The dropdown that contains the combobox options.

NgpComboboxInput

The input field for the combobox.

NgpComboboxOption

The individual options within the combobox dropdown.

NgpComboboxPortal

The portal for rendering the combobox dropdown in an overlay.

Animations

The ngpComboboxDropdown primitive adds a CSS custom property --ngp-combobox-transform-origin to the element that can be used to animate the menu from the trigger element.

The ngpComboboxDropdown will also add the data-enter and data-exit attributes to the element when it is being added or removed from the DOM. This can be used to trigger animations.

:host[data-enter] {
  animation: fade-in 0.2s ease-in-out;
}

:host[data-exit] {
  animation: fade-out 0.2s ease-in-out;
}

Global Configuration

You can configure the default options for all comboboxes in your application by using the provideComboboxConfig function in a providers array.

import { provideComboboxConfig } from 'ng-primitives/combobox';

bootstrapApplication(AppComponent, {
  providers: [provideComboboxConfig({ placement: 'bottom', container: document.body, flip: true })],
});

NgpComboboxConfig

Accessibility

Adheres to the WAI-ARIA guidelines for comboboxes.

Keyboard Interactions

The combobox supports comprehensive keyboard navigation whether or not an input field is present:

With Input Field

• ArrowDown: Open the dropdown and focus the first option. If the dropdown is already open, move focus to the next option.
• ArrowUp: Open the dropdown and focus the last option. If the dropdown is already open, move focus to the previous option.
• Home: Move focus to the first option (when dropdown is open).
• End: Move focus to the last option (when dropdown is open).
• Enter: Toggle the selection state of the focused option. In single selection mode, this will select the option and close the dropdown. In multiple selection mode, this will toggle the option without closing the dropdown.
• Escape: Close the dropdown without selecting an option.
• Any character key: Open the dropdown and filter options based on typed text.

Without Input Field

When no ngpComboboxInput is present, the combobox container becomes focusable and supports:

• Tab: Focus the combobox container.
• ArrowDown: Open the dropdown and focus the first option. If already open, move to the next option.
• ArrowUp: Open the dropdown and focus the last option. If already open, move to the previous option.
• Home: Move focus to the first option (when dropdown is open).
• End: Move focus to the last option (when dropdown is open).
• Enter: Select the focused option and close the dropdown.
• Escape: Close the dropdown without selecting an option.