ngx-mat-combobox
TypeScript icon, indicating that this package has built-in type declarations

1.0.3 • Public • Published

NgxMatCombobox

Customizable Combobox component for Angular Material

Demo + code examples

Screenshot

Features

  • Single & Multiple selection :)
  • Autocomplete
  • Chips
  • Custom templates for options, header, footer, loading overlay, no options etc..

TODO

  • Tests
  • Documentation
  • Theming support

Installation

npm -i ngx-mat-combobox

Example

For more details see examples or projects/demo application

Components

  • ngx-mat-combobox
@Input Type Description
options any[] List of strings or complex objects. Default [].
valueAccessor string | NgxMatComboboxAccessorFn Property of option's object which holds the 'value' or NgxMatComboboxAccessorFn.
labelAccessor string | NgxMatComboboxAccessorFn Property of option's object which holds the 'label' or NgxMatComboboxAccessorFn.
displayAccessor string | NgxMatComboboxAccessorFn Property of option's object which holds the 'selected label' or NgxMatComboboxAccessorFn. If not defined labelAccessor will be used.
disabledAccessor string | NgxMatComboboxAccessorFn Property of option's object which holds the 'disabled state' or NgxMatComboboxAccessorFn.
mapOptionsFn NgxMatComboboxMapOptionsFn Default undefined.
filterOptionsFn NgxMatComboboxFilterOptionsFn Default undefined.
compareOptionsFn NgxMatComboboxCompareOptionsFn
trackOptionByFn TrackByFunction
multiple boolean Multiple selection mode. Default false.
maxValues number Limit maximum selected options. Default 0 (no limit).
useValue boolean If set, component will emit option's value using provided valueAccessor. Default false.
autoActivate boolean If set, first available option id dropdown will be activated. Default false.
autoOpen boolean If set, dropdown will open when form field is focused. Default false.
autoSelect boolean If set, value model is updated when option is activated (e.g. focused by key navigation). Default false.
fillInput boolean If set, search input is updated using displayAccessor value. Works only in single selection mode. Default false.
autocomplete boolean Autocomplete mode. Default false.
autocompleteMinChars number Default 0.
autocompleteDebounceInterval number Default 400.
noWrap boolean If set,selected options list will wrap. Default false.
showToggleTrigger boolean Default true.
showLoadingSpinner boolean Default true.
loadingSpinnerDiameter number Default undefined.
loadingSpinnerStrokeWidth number Default 2.
loadingSpinnerColor string Default 'primary'.
disableOptionsRipple boolean Default false.
useChips boolean Default false.
disableChipsRipple boolean Default false.
disableChipsRemove boolean Default false.
dropdownAlign 'start' | 'center' | 'end' Dropdown align. Default 'start'.
dropdownOffsetX number Default 0.
dropdownOffsetY number Default 0.
dropdownAutoFocus boolean Autofocus first element in custom dropdown template. Default false.
dropdownTrapFocus boolean Trap focus in custom dropdown template. Default false.
dropdownClass string Default undefined.
dropdownMatchFieldWidth boolean Dropdown width based on parent form field width. Default true.
dropdownKeyNavWrap boolean Dropdown key navigation wrap. Default true.
dropdownKeyNavHomeAndEnd boolean Dropdown key navigation HOME and END keys. Ignored in autocomplete mode. Default true.
dropdownKeyNavTypeAhead boolean Dropdown key navigation type ahead. Ignored in autocomplete mode. Default true.
noOptionText string Default 'No Results'.
dropdownBackdrop boolean Default false.
dropdownBackdropClass string Default undefined.
@Output Type Description
openedChange boolean
selectionChange any[]
Property Type Description
opened boolean
selectedOptions Observable<any[]>
filteredOptions Observable<any[]>
input? NgxMatComboboxInput
Method Returns Description
focus() void
closeDropdown() void
toggleDropdown() void
selectOption(option: any) void
selectOptions(option: any[]) void
deselectOption(option: any) void
deselectOptions(option: any[]) void
toggleOption(option: any) void
clear() void
isOptionSelected(option: any) boolean
getSelectedOptionIndex(option: any) number
getFilteredOptionIndex(option: any) number
filter(query: string) void
alignDropdown() void
scrollToOption(index: number) void
startLoading() void
stopLoading() void

Exported as ngxMatCombobox

Directives

  • ngxMatComboboxInput or ngx-mat-combobox-input

Exported as ngxMatComboboxInput

  • ngxMatComboboxRemove or ngx-mat-combobox-remove

Exported as ngxMatComboboxRemove.

Custom content templates

  • ngxMatComboboxOption or ngx-mat-combobox-option

  • ngxMatComboboxNoOption or ngx-mat-combobox-no-option

  • ngxMatComboboxDisplay or ngx-mat-combobox-display

  • ngxMatComboboxHeader or ngx-mat-combobox-header

  • ngxMatComboboxFooter or ngx-mat-combobox-footer

  • ngxMatComboboxLoading or ngx-mat-combobox-loading

Interfaces

Function to access object options properties.

export type NgxMatComboboxAccessorFn = (option: any) => any;

Function to map model values to the option objects.

export type NgxMatComboboxMapOptionsFn = (value: any[], options: any[]) => Observable<any[]> | any[];

Autocomplete filter function.

export type NgxMatComboboxFilterOptionsFn = (query: string, options: any[]) => Observable<any[]> | any[];

Function to compare two options. By default [valueAccessor] is used internally.

export type NgxMatComboboxCompareOptionsFn = (o1: any, o2: any) => boolean;

Defaults

export interface NgxMatComboboxDefaultOptions {
  valueAccessor?: string | NgxMatComboboxAccessorFn;
  labelAccessor?: string | NgxMatComboboxAccessorFn;
  displayAccessor?: string | NgxMatComboboxAccessorFn;
  disabledAccessor?: string | NgxMatComboboxAccessorFn;

  showToggleTrigger?: boolean;

  showLoadingSpinner?: boolean;
  loadingSpinnerDiameter?: number;
  loadingSpinnerStrokeWidth?: number;
  loadingSpinnerColor?: string;

  autocompleteMinChars?: number;
  autocompleteDebounceInterval?: number;

  noWrap?: boolean;
  noOptionText?: string;

  dropdownClass?: string,
  dropdownMatchFieldWidth?: boolean;
  dropdownOffsetX?: number;
  dropdownOffsetY?: number;

  dropdownKeyNavWrap?: boolean;
  dropdownKeyNavHomeAndEnd?: boolean;
  dropdownKeyNavTypeAhead?: boolean;

  disableOptionsRipple?: boolean;
  disableChipsRipple?: boolean;
  disableChipsRemove?: boolean;
}

Global configuration

  providers: [
    //...
    {
      provide: NGX_MAT_COMBOBOX_DEFAULT_OPTIONS, useValue: {
            autocompleteMinChars: 3,
            autocompleteDebounceInterval: 250,
            loadingSpinnerStrokeWidth: 4,
            loadingSpinnerColor: 'accent',
            showToggleTrigger: false,
            dropdownMatchFieldWidth: false,
          } as NgxMatComboboxDefaultOptions
    },
    //...
  ]

Package Sidebar

Install

npm i ngx-mat-combobox

Weekly Downloads

8

Version

1.0.3

License

MIT

Unpacked Size

725 kB

Total Files

24

Last publish

Collaborators

  • w3soto