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

1. Install package

   npm install ngx-virtual-select-field-filterable

2. Import bundle into your component

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

3. 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,
       }));
   }

4. 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>

5. 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: ...;
}