Primitives

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>

Reusable Component

Create a reusable component that uses the NgpCombobox directive.

import { Component } from '@angular/core';
import { Combobox } from './combobox';

@Component({
  selector: 'app-root',
  imports: [Combobox],
  template: `
    <app-combobox [options]="options" placeholder="Select a character" />
  `,
})
export default class App {
  readonly options: string[] = [
    'Marty McFly',
    'Doc Brown',
    'Biff Tannen',
    'George McFly',
    'Jennifer Parker',
    'Emmett Brown',
    'Einstein',
    'Clara Clayton',
    'Needles',
    'Goldie Wilson',
    'Marvin Berry',
    'Lorraine Baines',
    'Strickland',
  ];
}

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.
  • componentSuffix: The suffix to apply to the generated component class name.
  • fileSuffix: The suffix to apply to the generated component file name. Defaults to component.
  • exampleStyles: 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.

Data Attributes

The following data attributes are applied to the ngpCombobox directive:

Attribute Description
data-open Applied when the combobox is open.
data-disabled Applied when the combobox is disabled.
data-multiple Applied when the combobox is in multiple mode.
data-hover Applied when the combobox is hovered.
data-press Applied when the combobox is pressed.
data-focus Applied when the combobox has focus within it.

NgpComboboxButton

The button that toggles the combobox dropdown.

  • Selector: [ngpComboboxButton]
  • Exported As: ngpComboboxButton

Data Attributes

The following data attributes are applied to the ngpComboboxButton directive:

Attribute Description
data-open Applied when the combobox is open.
data-disabled Applied when the combobox is disabled.
data-multiple Applied when the combobox is in multiple mode.

NgpComboboxDropdown

The dropdown that contains the combobox options.

  • Selector: [ngpComboboxDropdown]
  • Exported As: ngpComboboxDropdown

CSS Custom Properties

The following CSS custom properties are applied to the ngpComboboxDropdown directive:

Property Description
--ngp-combobox-transform-origin The transform origin for the dropdown animation.
--ngp-combobox-width The width of the combobox dropdown.
--ngp-combobox-input-width The width of the combobox input field.
--ngp-combobox-button-width The width of the combobox button.

NgpComboboxInput

The input field for the combobox.

  • Selector: input[ngpComboboxInput]
  • Exported As: ngpComboboxInput

Data Attributes

The following data attributes are applied to the ngpComboboxInput directive:

Attribute Description
data-open Applied when the combobox is open.
data-disabled Applied when the combobox is disabled.
data-multiple Applied when the combobox is in multiple mode.

NgpComboboxOption

The individual options within the combobox dropdown.

  • Selector: [ngpComboboxOption]
  • Exported As: ngpComboboxOption
ngpComboboxOptionValue
any

The value of the option.

ngpComboboxOptionDisabled
boolean

The disabled state of the option.

Data Attributes

The following data attributes are applied to the ngpComboboxOption directive:

Attribute Description
data-selected Applied when the option is selected.
data-active Applied when the option is active.
data-disabled Applied when the option is disabled.

NgpComboboxPortal

The portal for rendering the combobox dropdown in an overlay.

  • Selector: [ngpComboboxPortal]
  • Exported As: ngpComboboxPortal

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;
}

Accessibility

Adheres to the WAI-ARIA guidelines for comboboxes.

Keyboard Interactions

  • ArrowDown: Open the dropdown and focus the first option. If the dropdown is already open, move focus to the next option.
  • ArrowUp: Move focus to the previous option.
  • Enter: Select the focused option and close the dropdown.
  • Escape: Close the dropdown without selecting an option.

Copyright © 2025 Angular Primitives