NgxMatCombobox
Customizable Combobox component for Angular Material
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
},
//...
]