ngx-virtual-select-field-filterable

Virtual Select component for Angular Material Form Field

Table of contents

• Description
• Getting started
• Examples
• Keyboard Shortcuts
• Customization
• API
  • NgxVirtualSelectFieldComponent
  • NgxVirtualSelectFieldOptionComponent
  • NgxVirtualSelectFieldOptionSelectionChangeEvent
  • NgxVirtualSelectFieldTriggerComponent
  • NgxVirtualSelectFieldOptionForDirective
  • NgxVirtualSelectFieldOptionModel
  • NGX_VIRTUAL_SELECT_FIELD_CONFIG
  • NgxVirtualSelectFieldConfig
  • CSS variables

Description

This package replicates the Angular Material Select component with virtual scroll capabilities using cdk-virtual-scroll. It provides most major features of the original Angular Material Select component. The goal of this package is to provide a similar API and features as the original Angular Material Select component but with virtual scroll capabilities for handling large datasets efficiently.

Features:

• Virtual scroll for large datasets (100,000+ items)
• Single select
• Multi select with checkboxes
• Select all checkbox (for multi-select with filter)
• Filterable options with search input
• Clearable selection
• Loading spinner for async data
• Integrates with Angular Material Form Field
• Reactive Forms and Template-driven forms support
• Custom trigger template
• Custom option template
• Full keyboard navigation and shortcuts
• Type-ahead search
• Theming through CSS variables

Not Supported Features for now:

• Animations
• Custom Error state matcher
• Custom scroll strategy
• Full accessibility (in progress)
• Option groups

Demo

Getting started

• Install package

  npm install ngx-virtual-select-field-filterable
  

• Import bundle into your component

  import { NgxVirtualSelectFieldBundle } from 'ngx-virtual-select-field-filterable';
  ...
  @Component({
    imports: [
      NgxVirtualSelectFieldBundle,
      ...
    ],
    ...
  })
  

• Create options collection in component. Options collection should be an array of objects with value and label properties. Optionally, you can add disabled property to disable specific options and getLabel() for type-ahead search.

  ...
  protected options: NgxVirtualSelectFieldOptionModel<number>[]
  
  constructor() {
    this.options = new Array(100000)
      .fill(null)
      .map((_, index) => ({
        value: index,
        label: `${index} Option`,
        disabled: index % 5 === 0,
      }));
  }
  

• Setup template markup. ngxVirtualSelectFieldOptionFor directive should be used to pass options collection to the component and provide custom option template.

  <mat-form-field>
    <mat-label>Virtual Select Field Example</mat-label>
    <ngx-virtual-select-field [value]="value">
      <ngx-virtual-select-field-option
       *ngxVirtualSelectFieldOptionFor="let option of options"
       [value]="option.value"
       [disabled]="option.disabled">
       {{ option.label }}
     </ngx-virtual-select-field-option>
    </ngx-virtual-select-field>
  </mat-form-field>
  

• Include theme styles. You can define your own theme with help of CSS variables or inherit from material theme.

  @use 'ngx-virtual-select-field-filterable/theme' as theme;
  
  @include theme.inherit-material-theme(); // this will inherit css variables from material theme
  

Examples

Basic setup with value input and output binding

<mat-form-field>
  <mat-label>Example</mat-label>
  <ngx-virtual-select-field [value]="value" (valueChange)="onValueChange($event)">
    <ngx-virtual-select-field-option
      *ngxVirtualSelectFieldOptionFor="let option of options" [value]="option.value">
      {{ option.label }}
    </ngx-virtual-select-field-option>
  </ngx-virtual-select-field>
</mat-form-field>

Form control integration

<mat-form-field>
  <mat-label>Form Control Example</mat-label>
  <ngx-virtual-select-field [formControl]="formControl">
    <ngx-virtual-select-field-option
      *ngxVirtualSelectFieldOptionFor="let option of options" [value]="option.value">
        {{ option.label }}
    </ngx-virtual-select-field-option>
  </ngx-virtual-select-field>
</mat-form-field>

Multi select

<mat-form-field>
  <mat-label>Multi Select Example</mat-label>
  <ngx-virtual-select-field [value]="value" multiple (valueChange)="onValueChange($event)">
    <ngx-virtual-select-field-option
      *ngxVirtualSelectFieldOptionFor="let option of options"
      [value]="option.value">
      {{ option.label }}
    </ngx-virtual-select-field-option>
  </ngx-virtual-select-field>
</mat-form-field>

Custom trigger template

<mat-form-field class="field">
  <mat-label>Custom Trigger Example</mat-label>
  <ngx-virtual-select-field multiple [(value)]="value">
    <ngx-virtual-select-field-trigger>
      {{ value.length }} selected
    </ngx-virtual-select-field-trigger>
    <ngx-virtual-select-field-option
      *ngxVirtualSelectFieldOptionFor="let option of options"
      [value]="option.value">
      {{ option.label }}
    </ngx-virtual-select-field-option>
  </ngx-virtual-select-field>
</mat-form-field>

Filterable select with search input

<mat-form-field>
  <mat-label>Filterable Example</mat-label>
  <ngx-virtual-select-field
    [value]="value"
    [filterable]="true"
    filterPlaceholder="Type to filter..."
    (valueChange)="onValueChange($event)">
    <ngx-virtual-select-field-option
      *ngxVirtualSelectFieldOptionFor="let option of options"
      [value]="option.value">
      {{ option.label }}
    </ngx-virtual-select-field-option>
  </ngx-virtual-select-field>
</mat-form-field>

Clearable select with clear button

<mat-form-field>
  <mat-label>Clearable Example</mat-label>
  <ngx-virtual-select-field
    [value]="value"
    [clearable]="true"
    multiple
    (valueChange)="onValueChange($event)">
    <ngx-virtual-select-field-option
      *ngxVirtualSelectFieldOptionFor="let option of options"
      [value]="option.value">
      {{ option.label }}
    </ngx-virtual-select-field-option>
  </ngx-virtual-select-field>
</mat-form-field>

Loading state for async data

<mat-form-field>
  <mat-label>Async Example</mat-label>
  <ngx-virtual-select-field
    [value]="value"
    [loading]="isLoading"
    (valueChange)="onValueChange($event)">
    <ngx-virtual-select-field-option
      *ngxVirtualSelectFieldOptionFor="let option of options"
      [value]="option.value">
      {{ option.label }}
    </ngx-virtual-select-field-option>
  </ngx-virtual-select-field>
</mat-form-field>

Keyboard Shortcuts

The component supports full keyboard navigation:

When Panel is Closed

Shortcut	Single Select	Multi Select
Space / Enter	Open panel	Open panel
Alt + ArrowDown	Open panel	Open panel
ArrowDown / ArrowUp	Navigate & select	Open panel
Type any character	Type-ahead search	Type-ahead search

When Panel is Open

Shortcut	Description
ArrowDown / ArrowUp	Navigate through options
Alt + ArrowDown / Alt + ArrowUp	Close panel
Enter / Space	Toggle selection of active option
Ctrl + A	Select/deselect all options (multi-select only)
Shift + ArrowDown / Shift + ArrowUp	Extend selection (multi-select only)
Home / End	Jump to first/last option
Page Up / Page Down	Navigate by page
Escape	Close panel
Tab	Select active item and close panel
Type any character	Type-ahead search (300ms debounce)

When Filter Input is Focused

Shortcut	Description
ArrowDown / ArrowUp	Move focus to options list
ArrowLeft / ArrowRight	Move cursor in filter input
Escape	Close panel
Tab	Close panel

Customization

Components supports custom templates for trigger and option elements. You can use ngx-virtual-select-field-trigger and ngx-virtual-select-field-option components to define custom templates.

There are number of input parameters available to specify specific behavior of the component.

Injection tokens might be used to customize all component instances

All styles are defined with css variables, so you can easily override them in your own styles.

See more in API section below.

API

NgxVirtualSelectFieldComponent

selector: ngx-virtual-select-field Component to define select field

Input	Type	Default	Description
panelWidth	string|number |null	auto	Width for overlay panel
optionHeight	number	48	Height for an option element
panelViewportPageSize	number	8	Amount of visible items in list
multiple	boolean	false	Enable multiple selection
tabIndex	number	0	Tab index for keyboard navigation
typeaheadDebounceInterval	number	300	Milliseconds to wait before navigating to active element after keyboard search
panelClass	string | string[] | null	null	CSS class to be added to the panel element
filterable	boolean	false	Enable filtering of options with search input
filterPlaceholder	string	'Search...'	Placeholder text for the filter input
filterClearable	boolean	true	Show clear button in filter input
clearable	boolean	false	Show clear button in select trigger to clear all selections
loading	boolean	false	Show loading spinner while data is being loaded
showSelectAll	boolean	true	Show select all checkbox when multiple and filterable are enabled
value	TValue[] | TValue | null	null	Value of the select field
placeholder	string	none	Placeholder for the select field
required	boolean	false	Define if field is required
disabled	boolean	false	Define if field is disabled

Output	Type	Description
valueChange	TValue | TValue[]	Value change output
selectionChange	NgxVirtualSelectFieldChange	Selection change output

NgxVirtualSelectFieldOptionComponent

selector: ngx-virtual-select-field-option Component to define option element

Input	Type	Default	Description
value (required)	TValue		Value of the option
disabled	boolean	false	Whether the option is disabled

Output	Type	Description
selectedChange	NgxVirtualSelectFieldOptionSelectionChangeEvent<TValue>	Option selected value change

NgxVirtualSelectFieldOptionSelectionChangeEvent

Interface to define option selection change event contract Properties:

Name	Type	Description
source	NgxVirtualSelectFieldOptionComponent<TValue>	Option component instance
value	TValue	Value of the option
selected	boolean	Whether the option is selected

NgxVirtualSelectFieldTriggerComponent

selector: ngx-virtual-select-field-trigger Directive to define custom trigger template

NgxVirtualSelectFieldOptionForDirective

selector: *ngxVirtualSelectFieldOptionFor Directive to define custom option template and iterate over options

Input	Type	Description
of (required)	NgxVirtualSelectFieldOptionModel<TValue>[]	Options collection

NgxVirtualSelectFieldOptionModel

Interface to define option model contract Properties:

Name	Type	Description
value	TValue	Value of the option
label	string	Label of the option
disabled?	boolean	Whether the option is disabled
getLabel() optional	(option: NgxVirtualSelectFieldOptionModel<TValue>) => string	Function to get label for type-ahead search

NGX_VIRTUAL_SELECT_FIELD_CONFIG

Injection token to define global configuration for all instances of the component Config see in NgxVirtualSelectFieldConfig interface

NgxVirtualSelectFieldConfig

Interface to define global configuration contract Properties:

Name	Type	Description
panelWidth	string|number	Width for overlay panel
overlayPanelClass	string | string[]	CSS class to be added to the panel element
optionHeight	number	Height for an option element
panelViewportPageSize	number	Amount of visible items in list
showSelectAll	boolean	Show select all checkbox when multiple and filterable

NgxVirtualSelectFieldChange

Class to define event for selectionChange output Properties:

Name	Type	Description
source	NgxVirtualSelectFieldComponent	Instance of the selector component
value	TValue or TValue[]	New selection value

CSS variables

All styles are defined with css variables, so you can easily override them in your own styles. CSS variables for main component:

:root {
  --ngx-virtual-select-field-trigger-text-color: ...;
  --ngx-virtual-select-field-trigger-text-color--disabled: ...;
  --ngx-virtual-select-field-trigger-font-family: ...;
  --ngx-virtual-select-field-trigger-line-height: ...;
  --ngx-virtual-select-field-trigger-font-size: ...;
  --ngx-virtual-select-field-trigger-font-weight: ...;
  --ngx-virtual-select-field-trigger-letter-spacing: ...;

  --ngx-virtual-select-field-placeholder-text-color: ...;
  --ngx-virtual-select-field-placeholder-transition: ...;

  --ngx-virtual-select-field-arrow-size: ...;
  --ngx-virtual-select-field-arrow-color--enabled: ...;
  --ngx-virtual-select-field-arrow-color--focused: ...;
  --ngx-virtual-select-field-arrow-color--invalid: ...;
  --ngx-virtual-select-field-arrow-color--disabled: ...;

  --ngx-virtual-select-field-panel-background: ...;
  --ngx-virtual-select-field-panel-box-shadow: ...;
  --ngx-virtual-select-field-panel-list-wrapper-padding: ...;

  --ngx-virtual-select-field-divider-color: ...;
  --ngx-virtual-select-field-filter-input-border-color: ...;
  --ngx-virtual-select-field-filter-input-border-color--focused: ...;
}

CSS variables for option component:

:root {
  --ngx-virtual-select-field-option-color: ...;
  --ngx-virtual-select-field-option-font-family: ...;
  --ngx-virtual-select-field-option-line-height: ...;
  --ngx-virtual-select-field-option-font-size: ...;
  --ngx-virtual-select-field-option-letter-spacing: ...;
  --ngx-virtual-select-field-option-font-weight: ...;

  --ngx-virtual-select-field-option-selected-state-label-text-color: ...;
  --ngx-virtual-select-field-option-background-color--active: ...;
  --ngx-virtual-select-field-option-background-color--hover: ...;
  --ngx-virtual-select-field-option-background-color--selected: ...;

  --ngx-virtual-select-field-option-disabled-state-opacity: ...;
  --ngx-virtual-select-field-option-gap: ...;
  --ngx-virtual-select-field-option-padding: ...;
}