Listbox

A listbox presents a set of choices and lets users select one or multiple options.

Import

Import the Listbox primitives from ng-primitives/listbox.

import { NgpListbox } from 'ng-primitives/listbox';

Usage

Assemble the listbox directives in your template.

<div ngpListbox>
  <div ngpListboxOption ngpListboxOptionValue="1">Option 1</div>
  <div ngpListboxOption ngpListboxOptionValue="2">Option 2</div>
  <div ngpListboxOption ngpListboxOptionValue="3">Option 3</div>
</div>

Reusable Component

Create a reusable component that uses the listbox directives.

Schematics

Generate a reusable listbox component using the Angular CLI.

ng g ng-primitives:primitive listbox

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.
• styles: How component styles should be generated. css (default) includes the full example styles; unstyled omits them entirely so you can style the component yourself.
• example-styles (deprecated): still supported for compatibility - true maps to styles: css, false maps to styles: unstyled.

Examples

Multi-Select Listbox

The listbox can be configured to allow multiple selections.

Listbox with Sections

The listbox can be configured to have sections and headers.

Listbox with popover

The listbox can be paired with the NgpPopover directive to create a dropdown listbox.

API Reference

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

NgpListbox

NgpListboxOption

NgpListboxSection

NgpListboxTrigger

Augments the popover trigger with listbox-specific behavior, such as opening the listbox when the arrow keys are pressed.

Accessibility

Adheres to the WAI-ARIA Listbox Design Pattern.

Keyboard Interactions

DOM focus stays on the listbox container; keyboard navigation moves the active descendant (aria-activedescendant) between options rather than focusing them individually.

• Arrow Down - Move the active descendant to the next option.
• Arrow Up - Move the active descendant to the previous option.
• Home - Move the active descendant to the first option.
• End - Move the active descendant to the last option.
• Space - Select the active option.
• Enter - Select the active option.
• Escape - Close the listbox.