@progress/kendo-angular-dropdowns
Version:
A wide variety of native Angular dropdown components including AutoComplete, ComboBox, DropDownList, DropDownTree, MultiColumnComboBox, MultiSelect, and MultiSelectTree
652 lines (651 loc) • 23.6 kB
TypeScript
/**-----------------------------------------------------------------------------------------
* Copyright © 2025 Progress Software Corporation. All rights reserved.
* Licensed under commercial license. See LICENSE.md in the project root for more information
*-------------------------------------------------------------------------------------------*/
import { AdaptiveMode } from '../common/util';
import { SearchBarComponent } from '../common/searchbar.component';
import { Renderer2, ViewContainerRef, ElementRef, TemplateRef, OnDestroy, OnChanges, DoCheck, EventEmitter, AfterContentChecked, AfterViewInit, ChangeDetectorRef, KeyValueDiffers, NgZone, OnInit, Injector } from '@angular/core';
import { Observable } from 'rxjs';
import { SuffixTemplateDirective, PrefixTemplateDirective } from '@progress/kendo-angular-common';
import { AdaptiveSize, AdaptiveService } from '@progress/kendo-angular-utils';
import { FormControl } from '@angular/forms';
import { SelectionService, SelectionEvent } from '../common/selection/selection.service';
import { PopupSettings } from '../common/models/popup-settings';
import { NavigationService } from '../common/navigation/navigation.service';
import { DisabledItemsService } from '../common/disabled-items/disabled-items.service';
import { ItemDisabledFn } from '../common/disabled-items/item-disabled';
import { ItemTemplateDirective } from '../common/templates/item-template.directive';
import { CustomItemTemplateDirective } from '../common/templates/custom-item-template.directive';
import { GroupTemplateDirective } from '../common/templates/group-template.directive';
import { FixedGroupTemplateDirective } from '../common/templates/fixed-group-template.directive';
import { HeaderTemplateDirective } from '../common/templates/header-template.directive';
import { FooterTemplateDirective } from '../common/templates/footer-template.directive';
import { TagTemplateDirective } from '../common/templates/tag-template.directive';
import { GroupTagTemplateDirective } from '../common/templates/group-tag-template.directive';
import { NoDataTemplateDirective } from '../common/templates/no-data-template.directive';
import { PreventableEvent } from '../common/models/preventable-event';
import { RemoveTagEvent } from '../common/models/remove-tag-event';
import { LocalizationService } from '@progress/kendo-angular-l10n';
import { PopupService, PopupRef } from '@progress/kendo-angular-popup';
import { FilterableComponent } from '../common/filtering/filterable-component';
import { DataService } from '../common/data.service';
import { ListComponent } from '../common/list.component';
import { MultiSelectCheckableSettings } from '../common/models/checkboxes-settings';
import { VirtualizationSettings } from '../common/models/virtualization-settings';
import { PageChangeEvent } from '../common/models/page-change-event';
import { DropDownSize } from '../common/models/size';
import { DropDownRounded } from '../common/models/rounded';
import { DropDownFillMode } from '../common/models/fillmode';
import { SVGIcon } from '@progress/kendo-svg-icons';
import { ActionSheetComponent } from '@progress/kendo-angular-navigation';
import { TextBoxComponent } from '@progress/kendo-angular-inputs';
import { AdaptiveRendererComponent } from '../common/adaptive-renderer.component';
import { TagListComponent } from '../common/taglist.component';
import * as i0 from "@angular/core";
/**
* Represents the [Kendo UI MultiSelect component for Angular]({% slug overview_multiselect %}).
*
* Use the `MultiSelectComponent` to show a dropdown list where users can select multiple items.
* [See example]({% slug overview_multiselect %}).
*
* @example
* ```typescript
* @Component({
* selector: 'my-app',
* template: `
* <kendo-multiselect
* [data]="listItems"
* textField="name"
* valueField="id"
* placeholder="Select items...">
* </kendo-multiselect>
* `
* })
* export class AppComponent {
* public listItems = [
* { id: 1, name: "Item 1" },
* { id: 2, name: "Item 2" },
* { id: 3, name: "Item 3" }
* ];
* }
* ```
* @remarks
* Supported children components are: {@link CustomMessagesComponent}.
*/
export declare class MultiSelectComponent implements OnDestroy, OnChanges, OnInit, DoCheck, AfterContentChecked, AfterViewInit, FilterableComponent {
wrapper: ElementRef;
private localization;
private popupService;
private dataService;
private selectionService;
private navigationService;
private disabledItemsService;
private cdr;
private differs;
private renderer;
private _zone;
private injector;
hostElement: ElementRef;
private adaptiveService;
/**
* @hidden
*/
animationDuration: number;
/**
* @hidden
*/
xIcon: SVGIcon;
listBoxId: string;
tagListId: string;
tagPrefix: string;
optionPrefix: string;
popupRef: PopupRef;
text: string;
tags: any[];
focusedTagIndex: number;
/**
* @hidden
*/
adaptiveRendererComponent: AdaptiveRendererComponent;
/**
* @hidden
*/
get actionSheet(): ActionSheetComponent;
/**
* @hidden
*/
get actionSheetSearchBar(): TextBoxComponent;
/**
* @hidden
*/
get ariaControls(): string;
/**
* @hidden
*/
get isControlRequired(): boolean;
/**
* @hidden
*/
get formControl(): FormControl;
/**
* Focuses a specific item in the MultiSelect based on the provided index.
* Sets the index to `-1` to focus the custom item if available.
* Pass `null` or an invalid index to remove focus.
*/
focusItemAt(index: number): void;
/**
* Focuses the MultiSelect input element.
*/
focus(): void;
/**
* @hidden
*/
handleInputFocus(): void;
/**
* Removes focus from the MultiSelect input element.
*/
blur(): void;
/**
* @hidden
*/
handleFocus(): void;
/**
* @hidden
*/
handleBlur(): void;
/**
* @hidden
*/
handleInputBlur(): void;
/**
* @hidden
*/
onPointerDown(event: any): void;
/**
* @hidden
*/
onResize(): void;
get appendTo(): ViewContainerRef;
/**
* Shows or hides the current group sticky header when using grouped data.
* By default the sticky header is displayed ([see example]({% slug grouping_autocomplete %}#toc-sticky-header)).
*/
showStickyHeader: boolean;
/**
* @hidden
*/
focusableId: string;
/**
* Controls whether the options list closes after item selection finishes ([see example]({% slug openstate_multiselect %}#toc-keeping-the-options-list-open-while-on-focus)).
* Set to `false` to keep the list open while the component has focus.
*
* @default true
*/
autoClose: boolean;
/**
* Controls the loading state of the MultiSelect.
* Set to `true` to display the loading indicator.
*/
loading: boolean;
/**
* Sets the data source for the MultiSelect.
* Provide the data as an array of items.
*/
set data(data: any[]);
get data(): any[];
/**
* Sets the selected values of the MultiSelect.
* Accepts primitive values (strings, numbers) or complex objects.
* Use the `valuePrimitive` property to define the value type.
* > The component ignores selected values that don't exist in the data source.
*/
set value(values: any[]);
get value(): any[];
/**
* Sets the field name that contains the item value in the data objects.
* Skip this property when your data contains only primitive values.
* Supports nested property paths like `category.id`.
*/
valueField: string;
/**
* Sets the field name that contains the item text in the data objects.
* Skip this property when your data contains only primitive values.
* Supports nested property paths like `category.name`.
*/
textField: string;
/**
* Sets the [`tabindex`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex) attribute of the component.
*
* @default 0
*/
tabindex: number;
/**
* @hidden
*/
set tabIndex(tabIndex: number);
get tabIndex(): number;
/**
* Sets the size of the component.
*
* @default "medium"
*/
set size(size: DropDownSize);
get size(): DropDownSize;
/**
* Sets the border radius of the component.
*
* @default "medium"
*/
set rounded(rounded: DropDownRounded);
get rounded(): DropDownRounded;
/**
* Sets the fill mode of the component.
*
* @default "solid"
*/
set fillMode(fillMode: DropDownFillMode);
get fillMode(): DropDownFillMode;
/**
* Sets the placeholder text for the MultiSelect input.
* When the values are selected, it disappears.
*/
set placeholder(text: string);
get placeholder(): string;
/**
* Controls the adaptive mode behavior of the component.
* Set to `auto` to enable adaptive rendering on small screens.
*
* @default "none"
*/
adaptiveMode: AdaptiveMode;
/**
* Sets the title text for the ActionSheet in adaptive mode.
* Uses the component's label text by default.
*/
adaptiveTitle: string;
/**
* Sets the subtitle text for the ActionSheet in adaptive mode.
* No subtitle appears by default.
*/
adaptiveSubtitle: string;
/**
* @hidden
*/
get isAdaptiveModeEnabled(): boolean;
/**
* Controls the disabled state of the component.
* When true, sets the component to disabled.
* To learn how to disable the component in reactive forms, refer to the article on [Forms Support](slug:formssupport_multiselect#toc-managing-the-multiselect-disabled-state-in-reactive-forms).
*
* @default false
*/
disabled: boolean;
/**
* Determines wether the item will be disabled. The function is executed for each data item.
* The function receives the item as an argument and should return `true` if the item is disabled.
*/
set itemDisabled(fn: ItemDisabledFn);
/**
* Controls whether checkboxes appear before each item in the popup list.
* Pass `true` to enable checkboxes or an object to configure checkbox settings.
*
* @default false
*/
set checkboxes(settings: MultiSelectCheckableSettings | boolean);
get checkboxes(): MultiSelectCheckableSettings;
/**
* Controls the read-only state of the component.
* When true, the component does not allow user input or selection changes.
*
* @default false
*/
readonly: boolean;
/**
* Enables the filtering functionality of the MultiSelect.
* Set to `true` to allow users to filter the data by typing.
*
* @default false
*/
filterable: boolean;
/**
* Enables virtualization to improve performance with large datasets.
* Pass `true` for default settings or an object to configure virtualization.
*/
set virtual(settings: boolean | VirtualizationSettings);
get virtual(): VirtualizationSettings;
/**
* Configures the popup appearance and behavior.
* Set properties like `animate`, `width`, `height`, `popupClass`, and `appendTo`.
*/
set popupSettings(settings: PopupSettings);
get popupSettings(): PopupSettings;
/**
* Sets the height of the options list in the popup.
* This affects only the list height, not the entire popup container.
*
* @default 200
*/
set listHeight(_listHeight: number);
get listHeight(): number;
private _listHeight;
/**
* Controls the type of selected values.
* Set to `true` for primitive values or `false` for object references.
* When undefined, the component determines the type based on `valueField`.
*/
set valuePrimitive(isPrimitive: boolean);
get valuePrimitive(): boolean;
/**
* Controls whether a clear button appears when items are selected.
* Set to `true` to show the button that clears all selections.
*
* @default true
*/
clearButton: boolean;
/**
* Sets a function that transforms selected data items into display tags.
* Use this to customize how selected items appear as tags.
*
* @default (tags) => tags || []
*/
tagMapper: (tags: any) => any;
/**
* Allows users to add custom values not present in the data source.
* Set to `true` to enable custom value input.
* This feature is not available in adaptive mode.
*
* @default false
*/
allowCustom: boolean;
/**
* Sets a function that normalizes custom user input into data items.
* Use this when your data items differ from simple strings.
*/
valueNormalizer: (text: Observable<string>) => Observable<any>;
/**
* Sets HTML attributes for the inner input element.
* You cannot change attributes essential for component functionality.
*/
inputAttributes: {
[key: string]: string;
};
/**
* Fires when the user types in the input field.
* Use this event to filter the data source based on user input.
*/
filterChange: EventEmitter<string>;
/**
* Fires when the value changes through user interaction or the Clear button.
* This event does not fire when you change the value programmatically.
*/
valueChange: EventEmitter<any[]>;
/**
* Fires before the popup opens.
* You can prevent the popup from opening by calling `preventDefault()` on the event.
*/
open: EventEmitter<PreventableEvent>;
/**
* Fires after the popup opens completely.
*/
opened: EventEmitter<any>;
/**
* Fires before the popup closes.
* You can prevent the popup from closing by calling `preventDefault()` on the event.
*/
close: EventEmitter<PreventableEvent>;
/**
* Fires after the popup closes completely.
*/
closed: EventEmitter<any>;
/**
* Fires when the user focuses the MultiSelect component.
*/
onFocus: EventEmitter<any>;
/**
* Fires when the MultiSelect component loses focus.
*/
onBlur: EventEmitter<any>;
/**
* Fires when the user focuses the input element inside the MultiSelect.
*/
inputFocus: EventEmitter<any>;
/**
* Fires when the input element inside the MultiSelect loses focus.
*/
inputBlur: EventEmitter<any>;
/**
* Fires before a tag gets removed from the selection.
* You can prevent tag removal by calling `preventDefault()` on the event.
*/
removeTag: EventEmitter<RemoveTagEvent>;
container: ViewContainerRef;
searchbar: SearchBarComponent;
tagList: TagListComponent;
popupTemplate: TemplateRef<any>;
optionsList: ListComponent;
template: ItemTemplateDirective;
customItemTemplate: CustomItemTemplateDirective;
groupTemplate: GroupTemplateDirective;
fixedGroupTemplate: FixedGroupTemplateDirective;
headerTemplate: HeaderTemplateDirective;
footerTemplate: FooterTemplateDirective;
tagTemplate: TagTemplateDirective;
groupTagTemplate: GroupTagTemplateDirective;
noDataTemplate: NoDataTemplateDirective;
/**
* @hidden
*/
suffixTemplate: SuffixTemplateDirective;
/**
* @hidden
*/
prefixTemplate: PrefixTemplateDirective;
hostClasses: boolean;
get dir(): string;
get disabledClass(): boolean;
get isLoading(): boolean;
/**
* @hidden
*/
windowSize: AdaptiveSize;
/**
* @hidden
*/
get isActionSheetExpanded(): boolean;
/**
* @hidden
*/
get isAdaptive(): boolean;
/**
* @hidden
*/
applyValue(): void;
disabledIndices: Set<number>;
private initialized;
private _size;
private _rounded;
private _fillMode;
private _valueHolder;
private isCustomValueSelected;
constructor(wrapper: ElementRef, localization: LocalizationService, popupService: PopupService, dataService: DataService, selectionService: SelectionService, navigationService: NavigationService, disabledItemsService: DisabledItemsService, cdr: ChangeDetectorRef, differs: KeyValueDiffers, renderer: Renderer2, _zone: NgZone, injector: Injector, hostElement: ElementRef, adaptiveService: AdaptiveService);
get listContainerClasses(): any[];
/**
* @hidden
*/
get customItemSizeClass(): any;
get width(): any;
get height(): any;
get activeDescendant(): string;
get clearButtonVisiblity(): string;
/**
* @hidden
*/
verifySettings(): void;
/**
* @hidden
*/
change(event: SelectionEvent): void;
/**
* @hidden
*/
setState(value: any[]): void;
/**
* @hidden
*/
handleFilter(text: string): void;
/**
* @hidden
*/
pageChange(event: PageChangeEvent): void;
/**
* @hidden
*/
clearFilter(): void;
/**
* @hidden
*/
handleNavigate(event: any): void;
/**
* @hidden
*/
handleRemoveTag({ tag }: {
tag: any;
index?: number;
}): void;
/**
* @hidden
*/
clearAll(event?: any): void;
/**
* @hidden
*/
protected addCustomValue(text: string): void;
ngAfterContentChecked(): void;
ngDoCheck(): void;
ngOnInit(): void;
ngOnChanges(changes: any): void;
ngAfterViewInit(): void;
ngOnDestroy(): void;
/**
* Toggles the visibility of the popup or actionSheet
* ([see example]({% slug openstate_multiselect %}#toc-setting-the-initially-opened-component)).
* If you use the `toggle` method to open or close the popup or actionSheet, the respective `open` and `close` events will not be fired.
*
* @param open - The state of the popup.
*/
toggle(open?: boolean): void;
/**
* Returns the current open state. Returns `true` if the popup or actionSheet is open.
*/
get isOpen(): boolean;
/**
* Resets the MultiSelect by clearing the text and value.
* This method does not trigger the `selectionChange` and `valueChange` events.
*/
reset(): void;
/**
* @hidden
*/
messageFor(key: string): string;
/**
* @hidden
*/
writeValue(value: any): void;
/**
* @hidden
*/
registerOnChange(fn: any): void;
/**
* @hidden
*/
registerOnTouched(fn: any): void;
/**
* @hidden
*/
setDisabledState(isDisabled: boolean): void;
/**
* @hidden
*/
onTagMapperChange(): void;
/**
* @hidden
*/
handleClick(): void;
protected onChangeCallback: Function;
protected onTouchedCallback: Function;
private _placeholder;
private _open;
private _value;
private _popupSettings;
private _virtualSettings;
private _valuePrimitive;
private _checkboxes;
private _isFocused;
set isFocused(isFocused: boolean);
get isFocused(): boolean;
private selectedDataItems;
private popupPointerDownHandler;
private isOpenPrevented;
private customValueSubject;
private customValueSubscription;
private subs;
private touchstartDisposeHandler;
private direction;
private differ;
private valueChangeDetected;
private subscribeEvents;
private subscribeTouchEvents;
private unsubscribeEvents;
private removeGroupTag;
private removeSingleTag;
/**
* @hidden
*
* Determines which of the provided tags should be disabled and stores their position indices
*/
private disabledItemsMapper;
private createCustomValueStream;
private handleItemChange;
private handleMousedown;
private handleKeydown;
private handleEnter;
private handleClose;
private handleEnd;
private handleHome;
private sortSelectionAscending;
private handleSelectAll;
private handleSelectAllToBeginning;
private handleSelectAllToEnd;
private handleSelectUpDown;
/**
* Selects all items between the focused item and the last clicked item (index). Also removes all other selected items.
*/
private selectRangeFromTo;
private handleUp;
private handleBackspace;
private handleDelete;
private handleLeftKey;
private handleDownKey;
private handleRightKey;
private findIndex;
private searchTextAndFocus;
private closePopup;
private openPopup;
/**
* @hidden
*/
togglePopup(open: boolean): void;
private triggerPopupEvents;
private _toggle;
private destroyPopup;
private createPopup;
private emitValueChange;
private resolveDataItemFromTags;
private firstFocusableIndex;
private nextTick;
private setComponentClasses;
private openActionSheet;
private blurComponent;
static ɵfac: i0.ɵɵFactoryDeclaration<MultiSelectComponent, never>;
static ɵcmp: i0.ɵɵComponentDeclaration<MultiSelectComponent, "kendo-multiselect", ["kendoMultiSelect"], { "showStickyHeader": { "alias": "showStickyHeader"; "required": false; }; "focusableId": { "alias": "focusableId"; "required": false; }; "autoClose": { "alias": "autoClose"; "required": false; }; "loading": { "alias": "loading"; "required": false; }; "data": { "alias": "data"; "required": false; }; "value": { "alias": "value"; "required": false; }; "valueField": { "alias": "valueField"; "required": false; }; "textField": { "alias": "textField"; "required": false; }; "tabindex": { "alias": "tabindex"; "required": false; }; "tabIndex": { "alias": "tabIndex"; "required": false; }; "size": { "alias": "size"; "required": false; }; "rounded": { "alias": "rounded"; "required": false; }; "fillMode": { "alias": "fillMode"; "required": false; }; "placeholder": { "alias": "placeholder"; "required": false; }; "adaptiveMode": { "alias": "adaptiveMode"; "required": false; }; "adaptiveTitle": { "alias": "adaptiveTitle"; "required": false; }; "adaptiveSubtitle": { "alias": "adaptiveSubtitle"; "required": false; }; "disabled": { "alias": "disabled"; "required": false; }; "itemDisabled": { "alias": "itemDisabled"; "required": false; }; "checkboxes": { "alias": "checkboxes"; "required": false; }; "readonly": { "alias": "readonly"; "required": false; }; "filterable": { "alias": "filterable"; "required": false; }; "virtual": { "alias": "virtual"; "required": false; }; "popupSettings": { "alias": "popupSettings"; "required": false; }; "listHeight": { "alias": "listHeight"; "required": false; }; "valuePrimitive": { "alias": "valuePrimitive"; "required": false; }; "clearButton": { "alias": "clearButton"; "required": false; }; "tagMapper": { "alias": "tagMapper"; "required": false; }; "allowCustom": { "alias": "allowCustom"; "required": false; }; "valueNormalizer": { "alias": "valueNormalizer"; "required": false; }; "inputAttributes": { "alias": "inputAttributes"; "required": false; }; }, { "filterChange": "filterChange"; "valueChange": "valueChange"; "open": "open"; "opened": "opened"; "close": "close"; "closed": "closed"; "onFocus": "focus"; "onBlur": "blur"; "inputFocus": "inputFocus"; "inputBlur": "inputBlur"; "removeTag": "removeTag"; }, ["template", "customItemTemplate", "groupTemplate", "fixedGroupTemplate", "headerTemplate", "footerTemplate", "tagTemplate", "groupTagTemplate", "noDataTemplate", "suffixTemplate", "prefixTemplate"], never, true, never>;
}