Class

TelerikDropDownList<TItem, TValue>

Declaration

public TelerikDropDownList()

Creates a default placeholder item displayed when no value is selected, allowing users to clear their selection. The default item uses default(TValue) as its value, which is null for reference types and default values for value types. Example: "Select a country", "Choose an option", "-- None --". When users select this item, the bound Value becomes default(TValue).

Declaration

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

Property Value

Configures advanced dropdown popup behavior including animations, positioning, dimensions, and collision detection. Use to customize popup opening animations, set size constraints, control positioning relative to the input, or handle viewport collisions. Children: DropDownListPopupSettings component with properties for animation duration, popup dimensions, and positioning options.

Declaration

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

Property Value

Controls the delay in milliseconds between when a user stops typing and when the filter operation executes. Prevents excessive filtering during rapid typing, improving performance with large datasets or server-side filtering. Lower values (50-100ms) provide more responsive filtering but may impact performance with slow data sources. Higher values (200-500ms) reduce server requests but may feel less responsive to users. Recommended range: 100-300ms for optimal balance of responsiveness and performance.

Declaration

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

Property Value

Controls how the dropdown filters data when Filterable is enabled. StartsWith filters items that begin with the user input - fastest and most intuitive for sorted lists. Contains searches anywhere within the text - best for finding items in large unsorted datasets. EndsWith matches items ending with the input - useful for codes or suffixes. Filtering operates on the property specified by TextField using case-insensitive comparison.

Declaration

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

Property Value

Sets the placeholder text displayed in the filter input field when Filterable is enabled. Provides users with guidance on how to search through the dropdown options. Example: "Type to search...", "Filter items", "Search products". Appears only when the dropdown is open and filtering is enabled.

Declaration

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

Property Value

Customizes how each dropdown item appears in the selection list using a custom template. Provides access to each data item for displaying formatted content, icons, images, or complex layouts. Example: Show user profiles with avatars, format product listings with prices, or highlight search terms. Use CSS classes and conditional styling to create rich, interactive dropdown options. Children: allows arbitrary content including HTML elements, components, and data binding expressions.

Declaration

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

Property Value

Fires when the dropdown popup is about to close, regardless of whether a selection was made. Use for cleanup operations, saving draft selections, updating related UI components, or analytics tracking. The event provides information about why the popup closed (selection, escape key, outside click, etc.). Useful for implementing custom behaviors like confirming selections or handling partial user inputs.

Declaration

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

Property Value

Executes custom logic when each dropdown item renders, allowing dynamic CSS class assignment based on item data. Use to highlight specific items, indicate status, apply conditional styling, or add accessibility attributes. Example: Mark favorites with special colors, show disabled states, or highlight recently used items. The event provides access to the item data and allows setting custom CSS classes for individual list items.

Declaration

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

Property Value

Fires when the dropdown popup is about to open, allowing you to perform actions like loading additional data or analytics tracking. Use for lazy loading dropdown items, logging user interactions, or preparing dynamic content. Combine with OnClose to implement performance optimizations like loading data only when needed. The event provides context about the opening action and can be used for conditional data loading.

Declaration

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

Property Value

Fires when the dropdown needs to load data, enabling custom data operations like server-side filtering, paging, and sorting. Once implemented, you must handle all data operations yourself - the component will no longer perform automatic filtering or paging. Essential for large datasets, server-side filtering, or integration with external APIs and databases. Use with ValueMapper when implementing virtual scrolling with custom data loading.

Declaration

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

Property Value

Declaration

protected ListDataItem SelectedDataItem { get; set; }

Property Value

Specifies which property of the data items to display as text in the dropdown and selected value area. Must match a public property name on the TItem objects in Data. Example: For a Person object with Name and Age properties, use "Name" to show person names in the dropdown. Required when Data contains complex objects rather than primitive types like string or int.

Declaration

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

Property Value

Overrides TelerikSelectBase<TItem, TValue>.TextField

Provides a way to retrieve data items that correspond to specific values when using virtual scrolling with OnRead. Essential for pre-selecting items that may not be currently loaded in the virtual scroll window. The function receives a value and must return the corresponding data item, typically by querying your data source. Required when combining virtual scrolling with custom data loading to ensure proper value binding and display.

Declaration

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

Property Value

Customizes how the selected value appears in the dropdown input field using a custom template. Provides access to the selected data item for displaying formatted content, icons, or complex layouts. Example: Show user avatar and name, format dates, or display product details with images. Children: allows arbitrary content including HTML elements, components, and data binding expressions.

Declaration

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

Property Value

Declaration

protected override void BuildRenderTree(RenderTreeBuilder __builder)

Parameters

Overrides ComponentBase.BuildRenderTree(RenderTreeBuilder)

Declaration

public override void Dispose()

Overrides TelerikSelectBase<TItem, TValue>.Dispose()

Declaration

protected override Task OnAfterRenderAsync(bool firstRender)

Parameters

Returns

Overrides BaseComponent.OnAfterRenderAsync(bool)

Declaration

protected override Task OnParametersSetAsync()

Returns

Overrides TelerikSelectBase<TItem, TValue>.OnParametersSetAsync()

Declaration

public override Task SetParametersAsync(ParameterView parameters)

Parameters

Returns

Overrides TelerikSelectBase<TItem, TValue>.SetParametersAsync(ParameterView)