Class

TelerikMultiSelect<TItem, TValue>

Declaration

public TelerikMultiSelect()

Enables users to enter and select custom text values that don't exist in the predefined data source. When true, users can type any text and add it as a selection even if it's not in the dropdown list. Only works with string-based value types - use when TValue is string for proper type safety. REQUIREMENT: ValueField must point to a string property when enabled. UX: Essential for scenarios where users need flexibility beyond predefined options like tags or categories.

Declaration

[Parameter]
public bool AllowCustom { get; set; }

Property Value

Defines the ARIA describedby attribute to establish relationships between the MultiSelect and external descriptive content. Default behavior automatically references the internal selected tag list for screen reader accessibility. Override to reference custom help text, instructions, or error messages that describe the component's purpose or state. ACCESSIBILITY: Critical for screen readers to understand component context and provide meaningful descriptions to users. RESPONSIBILITY: When overriding, ensure the referenced element exists and provides valuable context for assistive technologies.

Declaration

[Parameter]
public override string AriaDescribedBy { get; set; }

Property Value

Overrides TelerikSelectBase<TItem, List<TValue>>.AriaDescribedBy

Controls whether the dropdown list automatically closes after users select an item. When true (default), dropdown closes after each selection for quick single-item workflows. When false, dropdown remains open for efficient multiple item selection without repeated opening. WORKFLOW: Disable for bulk selection scenarios where users need to pick many items quickly. MOBILE: Consider mobile UX when keeping dropdown open - may obscure other interface elements.

Declaration

[Parameter]
public bool AutoClose { get; set; }

Property Value

Sets the delay in milliseconds between when users stop typing and when the filtering operation triggers. Prevents excessive filtering calls while users are actively typing by waiting for a pause in input. Default value is 150ms, balancing responsive feedback with performance optimization. PERFORMANCE: Higher values reduce server requests but may feel less responsive to users. UX: Lower values provide immediate feedback but may cause performance issues with large datasets or slow connections.

Declaration

[Parameter]
public int DebounceDelay { get; set; }

Property Value

Defines how text filtering matches user input against data item text values. StartsWith matches items beginning with the typed text (default). Contains matches items containing the typed text anywhere within them. EndsWith matches items ending with the typed text. PERFORMANCE: StartsWith filtering is typically faster than Contains for large datasets. UX: Contains filtering provides more flexible search but may return too many results with short input.

Declaration

[Parameter]
public StringFilterOperator FilterOperator { get; set; }

Property Value

Customizes how individual items appear in the dropdown list using Razor markup templates. Children: allows arbitrary content including HTML, Blazor components, icons, badges, and interactive elements. Receives the current data item as context parameter, enabling dynamic content based on item properties. Use for rich item presentation with images, multi-line content, status indicators, or custom formatting. PERFORMANCE: Keep templates lightweight as they render for every visible item during scrolling.

Declaration

[Parameter]
public RenderFragment<TItem> ItemTemplate { get; set; }

Property Value

Sets the delay in milliseconds before showing the loading indicator when data is being fetched. Prevents flickering loading states for fast data operations while providing feedback for longer operations. Default value is 300ms, balancing immediate feedback with visual stability for typical data loading scenarios. PERFORMANCE: Higher values reduce loading indicator flicker but may leave users without feedback during longer loads. UX: Adjust based on typical data loading times - shorter for local data, longer for network operations.

Declaration

[Parameter]
public int LoaderShowDelay { get; set; }

Property Value

Limits how many individual item tags are shown before switching to a summary display format. When selections exceed this number, additional items are consolidated into a summary tag showing the count. Prevents interface overcrowding when many items are selected while maintaining visibility of primary selections. RELATIONSHIP: Works with TagMode and SummaryTagTemplate to control display behavior. UX: Set based on available space and importance of seeing individual vs. aggregate selection information.

Declaration

[Parameter]
public int? MaxAllowedTags { get; set; }

Property Value

Sets the minimum number of characters users must type before the dropdown list appears with filtering suggestions. Helps prevent overwhelming users with large datasets by requiring more specific input before showing options. Default value is 0, meaning the dropdown opens immediately when users start typing or click in the input. PERFORMANCE: Higher values reduce server requests and improve performance with large remote datasets. UX: Balance between immediate feedback (low values) and focused results (higher values) based on data size.

Declaration

[Parameter]
public int MinLength { get; set; }

Property Value

Defines custom content displayed before the selected item tags and input field. Children: allows arbitrary content including icons, labels, search controls, or branding elements. Content appears at the leftmost position inside the MultiSelect input container. Use for context indicators, category labels, or functional elements that enhance the selection experience. LAYOUT: Prefix content pushes tags and input field to the right within the available container width.

Declaration

[Parameter]
public RenderFragment MultiSelectPrefixTemplate { get; set; }

Property Value

Contains configuration settings for the MultiSelect dropdown popup behavior and appearance. Children: MultiSelectPopupSettings component with properties for positioning, animation, and responsive behavior. Use to customize popup dimensions, positioning logic, animation effects, and mobile-specific adaptations. MOBILE: Settings control how dropdown adapts to mobile devices, potentially switching to action sheet presentation. POSITIONING: Configure popup placement relative to the input, collision detection, and viewport boundaries.

Declaration

[Parameter]
public RenderFragment MultiSelectSettings { get; set; }

Property Value

Defines custom content displayed after the selected item tags and input field. Children: allows arbitrary content including action buttons, status indicators, or supplementary controls. Content appears at the rightmost position inside the MultiSelect input container before the clear/arrow buttons. Use for validation indicators, help buttons, or functional elements that complement the selection process. LAYOUT: Suffix content is positioned between the input area and built-in control buttons.

Declaration

[Parameter]
public RenderFragment MultiSelectSuffixTemplate { get; set; }

Property Value

Fires before the dropdown list closes, allowing customization or prevention of the closing action. Use for validation checks, data persistence, or cleanup operations before the dropdown becomes hidden. Event args support cancellation to prevent closing based on conditions like unsaved changes or required selections. TIMING: Occurs before dropdown animation starts, enabling smooth user experience with proper state management. ASYNC: Supports asynchronous operations for validation or data persistence before closing.

Declaration

[Parameter]
public EventCallback<MultiSelectCloseEventArgs> OnClose { get; set; }

Property Value

Fires each time a dropdown item is rendered, allowing customization of individual item appearance and styling. Use to conditionally apply CSS classes, modify item presentation, or highlight specific items based on their data. Event provides access to the current item's data and allows setting custom CSS classes for visual differentiation. PERFORMANCE: Keep logic lightweight as this fires for every visible item during rendering and scrolling. STYLING: Ideal for status indicators, priority highlighting, or conditional formatting based on item properties.

Declaration

[Parameter]
public Action<MultiSelectItemRenderEventArgs<TItem>> OnItemRender { get; set; }

Property Value

Fires before the dropdown list opens, allowing customization or prevention of the opening action. Use for dynamic data loading, permission checks, or UI state preparation before users see dropdown options. Event args support cancellation to prevent opening based on conditions like loading states or validation. TIMING: Occurs before dropdown animation starts, enabling smooth user experience with proper preparation. ASYNC: Supports asynchronous operations for data preparation or validation checks.

Declaration

[Parameter]
public EventCallback<MultiSelectOpenEventArgs> OnOpen { get; set; }

Property Value

Fires when the component needs to retrieve data, enabling custom data loading and server-side operations. Use this event to implement filtering, paging, sorting, or loading data from external sources like APIs. Once attached, you take full control of data operations - the component will no longer perform automatic filtering. REQUIREMENT: When used with virtual scrolling, implement ValueMapper for proper pre-selection of unloaded items. PERFORMANCE: Essential for handling large datasets efficiently through server-side processing.

Declaration

[Parameter]
public EventCallback<MultiSelectReadEventArgs> OnRead { get; set; }

Property Value

Controls whether the user's filter text remains in the input field after selecting an item from the dropdown. When true, preserves the typed filter text for continued filtering and selection of additional items. When false, clears the filter text after each selection to reset the view to all available options. REQUIREMENT: Only effective when filtering is enabled and AutoClose is set to false. UX: Enable for power users who want to make multiple selections from filtered results efficiently.

Declaration

[Parameter]
public bool PersistFilterOnSelect { get; set; }

Property Value

Sets the placeholder text displayed when no items are selected and the input field is empty. Provides helpful guidance about what users should select or how they should interact with the component. Placeholder disappears when focus is received or when any items are selected to avoid visual clutter. ACCESSIBILITY: Placeholder text should not be the only way to convey required information - use proper labels. UX: Keep placeholder text short and actionable like "Choose options" or "Select categories".

Declaration

[Parameter]
public string Placeholder { get; set; }

Property Value

Controls whether a dropdown arrow button appears at the right side of the input, providing visual indication of dropdown functionality. When visible, users can click the arrow to open/close the dropdown list in addition to clicking in the input area. Arrow provides clear visual cue that the component has dropdown behavior, especially important for accessibility and discoverability. Default value is false - enable when you want explicit dropdown button for enhanced usability. MOBILE: Arrow buttons are more touch-friendly on mobile devices than input area clicks.

Declaration

[Parameter]
public bool ShowArrowButton { get; set; }

Property Value

Controls whether a clear button (X) appears when items are selected, allowing users to remove all selections at once. Button appears on hover or focus when the MultiSelect contains selected values, positioned in the input area. When clicked, removes all selected items and resets the component to its empty state. Default value is true to provide easy bulk deselection functionality for better user experience. ACCESSIBILITY: Clear button is keyboard accessible and announces its purpose to screen readers.

Declaration

[Parameter]
public bool ShowClearButton { get; set; }

Property Value

Controls whether a visual separator line appears after the prefix content. When true, displays a vertical divider between MultiSelectPrefixTemplate and the main input area. Helps visually distinguish prefix content from the interactive selection area for better user experience. Default value is true to maintain clear visual boundaries between content sections. DESIGN: Separator uses theme-appropriate styling to match the overall component appearance.

Declaration

[Parameter]
public bool ShowPrefixSeparator { get; set; }

Property Value

Controls whether a visual separator line appears before the suffix content. When true, displays a vertical divider between the main input area and MultiSelectSuffixTemplate. Helps visually distinguish the interactive selection area from suffix content for better user experience. Default value is true to maintain clear visual boundaries between content sections. DESIGN: Separator uses theme-appropriate styling to match the overall component appearance.

Declaration

[Parameter]
public bool ShowSuffixSeparator { get; set; }

Property Value

Customizes how the summary tag appears when multiple items are condensed into a single tag display. Children: allows arbitrary content with access to summary context including selected items and count information. Template receives MultiSelectSummaryTagTemplateContext<TItem> providing selected items and aggregate data. Use for custom count displays, item previews, or summary information that helps users understand their selections. TRIGGER: Displays when TagMode is Single or when selections exceed MaxAllowedTags in Multiple mode.

Declaration

[Parameter]
public RenderFragment<MultiSelectSummaryTagTemplateContext<TItem>> SummaryTagTemplate { get; set; }

Property Value

Controls how selected items are displayed as visual tags within the input area. Multiple displays each selected item as an individual removable tag. Single shows all selections condensed into one summary tag with count. RELATIONSHIP: Works with MaxAllowedTags to determine when to switch between individual and summary display. UX: Multiple mode provides item-level control, Single mode saves space with large selections.

Declaration

[Parameter]
public MultiSelectTagMode TagMode { get; set; }

Property Value

Customizes how selected items appear as individual tags (chips) within the input area using Razor markup. Children: allows arbitrary content including HTML, components, icons, and interactive elements for each selected item. Receives the selected data item as context parameter, enabling dynamic tag content based on item properties. Use for rich tag presentation with colors, icons, status indicators, or abbreviated text for space efficiency. RELATIONSHIP: Only applies when TagMode is Multiple for individual tags.

Declaration

[Parameter]
public RenderFragment<TItem> TagTemplate { get; set; }

Property Value

Defines the property name from data items to display as the visible text in dropdown options and selected tags. Must match a public property name on TItem objects that returns the display text. Works in combination with ValueField to separate what users see from what gets selected. Default value is "Text" which works with simple string collections or objects having a Text property. BINDING: Essential for displaying meaningful labels when working with complex objects or ID-based selections.

Declaration

[Parameter]
public override string TextField { get; set; }

Property Value

Overrides TelerikSelectBase<TItem, List<TValue>>.TextField

Provides a callback function that retrieves full data items corresponding to selected values, essential for virtual scrolling scenarios. Used when OnRead is implemented and selected values may reference items not currently loaded in the viewport. Function receives list of selected values and must return the corresponding complete data items for proper display. REQUIREMENT: Required when combining OnRead with virtual scrolling to enable pre-selection of unloaded items. ASYNC: Supports asynchronous operations for fetching item details from remote sources or databases.

Declaration

[Parameter]
public Func<List<TValue>, Task<List<TItem>>> ValueMapper { get; set; }

Property Value

Declaration

protected override void BuildRenderTree(RenderTreeBuilder __builder)

Parameters

Overrides ComponentBase.BuildRenderTree(RenderTreeBuilder)

Declaration

protected override Task OnAfterRenderAsync(bool firstRender)

Parameters

Returns

Overrides BaseComponent.OnAfterRenderAsync(bool)

Declaration

protected override Task OnParametersSetAsync()

Returns

Overrides TelerikSelectBase<TItem, List<TValue>>.OnParametersSetAsync()