Class SfDropDownList<TValue, TItem>

The DropDownList component allows users to select a single value that is non-editable from a list of predefined values.

Inheritance
System.Object
SfBaseComponent
SfDataBoundComponent
SfDropDownBase<TItem>
SfDropDownList<TValue, TItem>
SfComboBox<TValue, TItem>
Implements
Syncfusion.Blazor.DropDowns.IVirtualList<TItem>
Inherited Members
Syncfusion.Blazor.DropDowns.SfDropDownBase<TItem>.RenderListItemsAsync(System.Collections.Generic.IEnumerable<TItem>, Syncfusion.Blazor.DropDowns.FieldSettingsModel, Syncfusion.Blazor.Data.Query)
Syncfusion.Blazor.DropDowns.SfDropDownBase<TItem>.SetListDataAsync(System.Collections.Generic.IEnumerable<TItem>, Syncfusion.Blazor.DropDowns.FieldSettingsModel, Syncfusion.Blazor.Data.Query)
Syncfusion.Blazor.DropDowns.SfDropDownBase<TItem>.GetPropertyValue(System.Object, System.String)
Syncfusion.Blazor.DropDowns.SfDropDownBase<TItem>.ActionBeginAsync(System.Collections.Generic.IEnumerable<TItem>, Syncfusion.Blazor.Data.Query)
Syncfusion.Blazor.DropDowns.SfDropDownBase<TItem>.GetQuery(Syncfusion.Blazor.Data.Query)
Syncfusion.Blazor.DropDowns.SfDropDownBase<TItem>.OnInitializedAsync()
Syncfusion.Blazor.DropDowns.SfDropDownBase<TItem>.OnParametersSetAsync()
Syncfusion.Blazor.DropDowns.SfDropDownBase<TItem>.GetDataByText(System.String, System.String)
Syncfusion.Blazor.DropDowns.SfDropDownBase<TItem>.IncrementalSearch(System.String, System.Collections.Generic.IEnumerable<TItem>, System.Nullable<System.Int32>, System.Boolean)
Syncfusion.Blazor.DropDowns.SfDropDownBase<TItem>.Search(System.String, System.Collections.Generic.IEnumerable<TItem>, System.String, System.Boolean)
Syncfusion.Blazor.DropDowns.SfDropDownBase<TItem>.RenderItemsAsync(System.Collections.Generic.IEnumerable<TItem>)
Syncfusion.Blazor.DropDowns.SfDropDownBase<TItem>.HighlightSearch(System.String, System.String, System.Boolean, Syncfusion.Blazor.DropDowns.FilterType)
Syncfusion.Blazor.DropDowns.SfDropDownBase<TItem>.MainData
Syncfusion.Blazor.DropDowns.SfDropDownBase<TItem>.ListDataSource
Syncfusion.Blazor.DropDowns.SfDropDownBase<TItem>.DataId
Syncfusion.Blazor.DropDowns.SfDropDownBase<TItem>.ItemData
Syncfusion.Blazor.DropDowns.SfDropDownBase<TItem>.IsActionFailed
Syncfusion.Blazor.DropDowns.SfDropDownBase<TItem>.TotalCount
Syncfusion.Blazor.DropDowns.SfDropDownBase<TItem>.ComponentName
Namespace: Syncfusion.Blazor.DropDowns
Assembly: Syncfusion.Blazor.dll
Syntax
public class SfDropDownList<TValue, TItem> : SfDropDownBase<TItem>, IInputBase, IDropDowns, IVirtualList<TItem>
Type Parameters
Name Description
TValue

Specifies the value type.
TItem

Specifies the type of SfDropDownList.
Examples

In the following code example, a basic DropDownList component is initialized with simple list items.

<SfDropDownList TItem="string" TValue="string" DataSource="@MyList">
</SfDropDownList>
@code{
    protected List<string> MyList = new List<string>() { "Small", "Medium", "Large" };
}

Constructors

SfDropDownList()

Declaration
public SfDropDownList()

Fields

ASSERTIVE

specifies the assertive string.

Declaration
protected const string ASSERTIVE = "assertive"
Field Value
Type Description
System.String

BOTH

Declaration
protected const string BOTH = "both"
Field Value
Type Description
System.String

FALSE

Specifies the string false.

Declaration
protected const string FALSE = "false"
Field Value
Type Description
System.String

NO_DATA

Specifies the root class of base component.

Declaration
protected const string NO_DATA = "e-content e-dropdownbase e-nodata"
Field Value
Type Description
System.String

TRUE

Specifies the string true.

Declaration
protected const string TRUE = "true"
Field Value
Type Description
System.String

Properties

AllowFiltering

Gets or sets a value that indicates whether the filtering option is enabled or not.

Declaration
public bool AllowFiltering { get; set; }
Property Value
Type Description
System.Boolean

true, if the filtering option is enabled and show the filter bar (search box) in the pop-up; otherwise, false.The default value is false.
Remarks

The filter action retrieves the matched items using the Filtering event based on the characters typed in the search textbox.

CssClass

Gets or sets a CSS class string to customize the appearance of the SfDropDownList<TValue, TItem> component.

Declaration
public string CssClass { get; set; }
Property Value
Type Description
System.String

Accepts a CSS class string separated by space to customize the appearance. The default value is String.Empty.

Enabled

Gets or sets a value that indicates whether to enable or disable the DropDownListEvents<TValue, TItem> component.

Declaration
public bool Enabled { get; set; }
Property Value
Type Description
System.Boolean

true, if the Dropdown list component is enabled; otherwise, it is disabled. The default value is false.

EnablePersistence

Gets or sets whether to persist component's state between page reloads. When set to true, the Value property is persisted.

Declaration
public bool EnablePersistence { get; set; }
Property Value
Type Description
System.Boolean

true, if the component's state persistence is enabled. The default value is false.
Remarks

Component's Value property will be stored in browser local storage to persist component's state when page reloads.

EnableRtl

Gets or sets whether the right-to-left direction is enabled or not for the drop-down list component.

Declaration
public bool EnableRtl { get; set; }
Property Value
Type Description
System.Boolean

true, if the right to left direction is enabled for dropdown list component. The default value is false.

EnableVirtualization

Gets or sets a value indicating whether the virtual scrolling is enabled or not.

Declaration
public bool EnableVirtualization { get; set; }
Property Value
Type Description
System.Boolean

true if the virtual scrolling for dropdown list; otherwise, false. The default is false.
Remarks

To improve performance, the EnableVirtualization property is set to true.

FilterBarPlaceholder

Gets or sets the text that is displayed when the filter textbox has no text and removes the focus.

Declaration
public string FilterBarPlaceholder { get; set; }
Property Value
Type Description
System.String

The text that is displayed when the filter text box has no text. The default value is String.Empty.
Remarks

This property value is updated only when the AllowFiltering is enabled.

FilterDataSource

Declaration
protected IEnumerable<TItem> FilterDataSource { get; set; }
Property Value
Type Description
System.Collections.Generic.IEnumerable<TItem>

FilterQuery

Declaration
protected Query FilterQuery { get; set; }
Property Value
Type Description
Query

FloatLabelType

Gets or sets the floating label behavior of the dropdown list. The Placeholder text act as a lable.

Declaration
public FloatLabelType FloatLabelType { get; set; }
Property Value
Type Description
FloatLabelType

One of the FloatLabelType enumeration. The default value is Never
Remarks

If the FloatLabelType is Never, the placeholder text does not float as a label. If the FloatLabelType is Auto, the placeholder text will float above the DropDownList component as a label after focusing it. If the FloatLabelType is Always, the placeholder text is displayed as a label above the DropDownList component.

Examples

In the following code example, set the float lable as Auto.

<SfDropDownList TItem="string" TValue="string" DataSource="@MyList" Placeholder="Select a value" FloatLabelType="FloatLabelType.Auto">
</SfDropDownList>
@code{
    protected List<string> MyList = new List<string>() { "Small", "Medium", "Large" };
}

FooterTemplate

Gets or sets the customised design content and assigns it to the footer container of the pop-up list.

Declaration
public RenderFragment FooterTemplate { get; set; }
Property Value
Type Description
Microsoft.AspNetCore.Components.RenderFragment

The template content. The default value in null.
Examples
<SfDropDownList TItem="string" TValue="string" DataSource="@MyList">
    <DropDownListTemplates TItem="string">
        <FooterTemplate>
            <span class='footer'>Total list items: 3 </span>
        </FooterTemplate>
    </DropDownListTemplates>
</SfDropDownList>
@code{
    protected List<string> MyList = new List<string>() { "Small", "Medium", "Large" };
}

HeaderTemplate

Gets or sets the customised design content and assigns it to the header container of the popup list.

Declaration
public RenderFragment HeaderTemplate { get; set; }
Property Value
Type Description
Microsoft.AspNetCore.Components.RenderFragment

The template content. The default value in null.
Examples
<SfDropDownList TItem="string" TValue="string" DataSource="@MyList">
    <DropDownListTemplates TItem="string">
        <HeaderTemplate>
            <span class='header'> T-shirt size </span>
        </HeaderTemplate>
    </DropDownListTemplates>
</SfDropDownList>
@code{
    protected List<string> MyList = new List<string>() { "Small", "Medium", "Large" };
}

HtmlAttributes

Gets or sets a collection of additional attributes such as styles, class, and more that will be applied to the dropdown list element.

Declaration
public Dictionary<string, object> HtmlAttributes { get; set; }
Property Value
Type Description
System.Collections.Generic.Dictionary<System.String, System.Object>

The value as dictionary collection.The default value is null
Remarks

Additional attributes can be added by specifying as inline attributes or by specifying @attributes directive.

Examples
<SfDropDownList TItem="string" TValue="string" DataSource="@MyList" HtmlAttributes="@CustomAttribute">
</SfDropDownList>
@code{
    protected List<string> MyList = new List<string>() { "Small", "Medium", "Large" };
    Dictionary<string, object> CustomAttribute = new Dictionary<string, object>()
    {
        { "title", "Select T-shirt size" }
    }
}

ID

Gets or sets the unique identifier for DropDownListEvents<TValue, TItem> component.

Declaration
public string ID { get; set; }
Property Value
Type Description
System.String

Accepts a string value. The default value is String.Empty.
Remarks

You can specify only unique value.

Index

Gets or sets the index of the selected item in the dropdown list component.

Declaration
public Nullable<int> Index { get; set; }
Property Value
Type Description
System.Nullable<System.Int32>

The index of the selected items in the list. The default value is null which indicates that nothing is selected.
Remarks

Use this property to determine the index of the currently selected item in the list if the dropdown list component allows only one selection.

Exceptions
Type Condition
System.ArgumentOutOfRangeException

The index was set to less than -1, or greater than or equal to the number of items on the list at the time the list is rendered.

IndexChanged

Gets or sets the callback to trigger when the index changes.

Declaration
public EventCallback<Nullable<int>> IndexChanged { get; set; }
Property Value
Type Description
Microsoft.AspNetCore.Components.EventCallback<System.Nullable<System.Int32>>

An event callback function.

InputAttributes

Gets or sets a collection of additional attributes such as disabled, value, and more that will be applied to the dropdown list input element.

Declaration
public Dictionary<string, object> InputAttributes { get; set; }
Property Value
Type Description
System.Collections.Generic.Dictionary<System.String, System.Object>

The value as dictionary collection. The default value is null
Remarks

If you configured both the property and equivalent input attribute, then the component considers the property value.

IsAutoComplete

Declaration
protected bool IsAutoComplete { get; set; }
Property Value
Type Description
System.Boolean

IsComboBox

Declaration
protected bool IsComboBox { get; set; }
Property Value
Type Description
System.Boolean

IsCustomFilteringAction

Declaration
protected bool IsCustomFilteringAction { get; set; }
Property Value
Type Description
System.Boolean

IsDropDownList

Declaration
protected bool IsDropDownList { get; set; }
Property Value
Type Description
System.Boolean

IsPopupShown

Declaration
protected bool IsPopupShown { get; set; }
Property Value
Type Description
System.Boolean

ItemsCount

Gets or sets the number of items to be fetched in the popup when the EnableVirtualization property is enabled.

Declaration
public int ItemsCount { get; set; }
Property Value
Type Description
System.Int32

The number of list items to be fetched in dropdown list component. The default value is 5.

ListHeight

Declaration
protected int ListHeight { get; set; }
Property Value
Type Description
System.Int32

Placeholder

Gets or sets the text that is displayed when the dropdown list has no value and remove on the focus.

Declaration
public string Placeholder { get; set; }
Property Value
Type Description
System.String

The text that is displayed when the dropdown list has no value. The default value is String.Empty.
Remarks

The property depends on the FloatLabelType property, The placeholder text acts as a label.

PopupHeight

Gets or sets the height of the popup list.

Declaration
public string PopupHeight { get; set; }
Property Value
Type Description
System.String

The preferred height of the popup list in pixels or percentage of the dropdown list. The default value is 300px.
Remarks

This property accepts pixels or percentage value.

PopupWidth

Gets or sets the width of the popup list. By default, the popup width sets based on the width of the SfDropDownList<TValue, TItem> component.

Declaration
public string PopupWidth { get; set; }
Property Value
Type Description
System.String

The preferred width of the popup list in pixels or percentage of the dropdown list. The default value is 100%.
Remarks

This property accepts pixels or percentage value.

Readonly

Gets or sets a value indicating whether the SfDropDownList<TValue, TItem> is in read-only mode or not.

Declaration
public bool Readonly { get; set; }
Property Value
Type Description
System.Boolean

true if the dropdown list is in read-only mode; otherwise, false. The default is false.
Remarks

In read-only mode, the dropdown list popup can not be opened on click.

ShowClearButton

Gets or sets a value indicating whether to show or hide the clear button in the dropdown list. It helps to clear the selected value of a dropdown list on user intraction.

Declaration
public virtual bool ShowClearButton { get; set; }
Property Value
Type Description
System.Boolean

true if show the clear button in the dropdown list; otherwise, false. The default is false.
Remarks

When the clear button is clicked, Value, and Index properties are reset to null.

TabIndex

Gets or sets the location of the SfDropDownList<TValue, TItem> component in the tab order.

Declaration
public int TabIndex { get; set; }
Property Value
Type Description
System.Int32

The numeric index of the dropdown list in the tab order. The default value is 0.

Value

Gets the value of the selected item in the dropdown list component. This will be used with two-way binding.

Declaration
public TValue Value { get; set; }
Property Value
Type Description
TValue

The value of the selected item in the dropdown list component. The default is null.
Remarks

Use the Value property to specify or determine the value displayed in the SfDropDownList<TValue, TItem> component.

ValueChanged

Gets or sets a callback that trigger when the value changes.

Declaration
public EventCallback<TValue> ValueChanged { get; set; }
Property Value
Type Description
Microsoft.AspNetCore.Components.EventCallback<TValue>

An event callback function.

ValueExpression

Gets or sets an expression that identifies the bound value in the DropDownListEvents<TValue, TItem> component.

Declaration
public Expression<Func<TValue>> ValueExpression { get; set; }
Property Value
Type Description
System.Linq.Expressions.Expression<System.Func<TValue>>

ValueTemplate

Gets or sets the customised design content and assigns it to the selected list item in the input element of the component.

Declaration
public RenderFragment<TItem> ValueTemplate { get; set; }
Property Value
Type Description
Microsoft.AspNetCore.Components.RenderFragment<TItem>

The template content. The default value in null.
Examples
<SfDropDownList TItem="string" TValue="string" DataSource="@MyList">
    <DropDownListTemplates TItem="string">
        <ValueTemplate>
            <span> T-shirt size - @(context)</span>
        </ValueTemplate>
    </DropDownListTemplates>
</SfDropDownList>
@code{
    protected List<string> MyList = new List<string>() { "Small", "Medium", "Large" };
}

Width

Gets or sets the width of the SfDropDownList<TValue, TItem> component.

Declaration
public string Width { get; set; }
Property Value
Type Description
System.String

The preferred width of the dropdown list in pixels or percentage value. The default value is 100%.

Methods

BuildRenderTree(RenderTreeBuilder)

Declaration
protected override void BuildRenderTree(RenderTreeBuilder __builder)
Parameters
Type Name Description
Microsoft.AspNetCore.Components.Rendering.RenderTreeBuilder __builder

ClearAllAsync(EventArgs, Boolean)

Task which used to clear all the items.

Declaration
protected virtual Task ClearAllAsync(EventArgs arguments = null, bool IsProgrammaticallyCleared = false)
Parameters
Type Name Description
System.EventArgs arguments

Specifies the EventArgs arguments.
System.Boolean IsProgrammaticallyCleared

Indicates whether the value is cleared manually or not, Default is false.
Returns
Type Description
System.Threading.Tasks.Task

Task.

ClearAsync()

Clear out the selected values from the SfDropDownList<TValue, TItem> component and sets the Value and Index properties as null.

Declaration
public Task ClearAsync()
Returns
Type Description
System.Threading.Tasks.Task

Task.

DropDownClickHandlerAsync()

Triggers while clicking the dropdown icon.

Declaration
protected Task DropDownClickHandlerAsync()
Returns
Type Description
System.Threading.Tasks.Task

Task.

FilterAsync(IEnumerable<TItem>, Query, FieldSettingsModel)

To filter the data from given data source by using query.

Declaration
public Task FilterAsync(IEnumerable<TItem> dataSource, Query query = null, FieldSettingsModel fields = null)
Parameters
Type Name Description
System.Collections.Generic.IEnumerable<TItem> dataSource

Specifies the data source.
Query query

Specifies the query.
FieldSettingsModel fields

Specifies the fields.
Returns
Type Description
System.Threading.Tasks.Task

Task.

FilterInputKeyUpHandlerAync(KeyboardEventArgs)

Specifies the keyup event of filter event.

Declaration
protected Task FilterInputKeyUpHandlerAync(KeyboardEventArgs arguments)
Parameters
Type Name Description
Microsoft.AspNetCore.Components.Web.KeyboardEventArgs arguments

Specifies the KeyboardEventArgs arguments.
Returns
Type Description
System.Threading.Tasks.Task

Task.

FocusAsync()

Sets the focus to the SfDropDownList<TValue, TItem> component for interaction.

Declaration
public Task FocusAsync()
Returns
Type Description
System.Threading.Tasks.Task

Task.

FocusOutAsync()

Remove the focus from the SfDropDownList<TValue, TItem> component, if the component is in focus state.

Declaration
public Task FocusOutAsync()
Returns
Type Description
System.Threading.Tasks.Task

Task.

FocusOutHandlerAsync(FocusEventArgs, Boolean)

Triggers when the component get focused out.

Declaration
protected Task FocusOutHandlerAsync(FocusEventArgs arguments, bool isFilterinput = false)
Parameters
Type Name Description
Microsoft.AspNetCore.Components.Web.FocusEventArgs arguments

Specifies the FocusEventArgs arguments.
System.Boolean isFilterinput

Specifies whether it is a filter input or not.
Returns
Type Description
System.Threading.Tasks.Task

Task.

GetDataByValue(TValue)

Retrieves all field values in the record that match the given value.

Declaration
public TItem GetDataByValue(TValue ddlValue)
Parameters
Type Name Description
TValue ddlValue

TValue
Returns
Type Description
TItem

The field value.

GetItemsAsync()

Retrieves all the list of items bound in the SfDropDownList<TValue, TItem> component.

Declaration
public Task<IEnumerable<TItem>> GetItemsAsync()
Returns
Type Description
System.Threading.Tasks.Task<System.Collections.Generic.IEnumerable<TItem>>

Task.

GetSkeletonCount(Boolean)

Declaration
protected void GetSkeletonCount(bool RetainSkeleton = false)
Parameters
Type Name Description
System.Boolean RetainSkeleton

HidePopupAsync()

Hides the SfDropDownList<TValue, TItem> popup list.

Declaration
public Task HidePopupAsync()
Returns
Type Description
System.Threading.Tasks.Task

Task.

HideSpinnerAsync()

Hides the data loading spinner.

Declaration
public Task HideSpinnerAsync()
Returns
Type Description
System.Threading.Tasks.Task

Task.

RefreshDataAsync()

Refreshes the popup list items. The method is useful if the popup list item changed externally.

Declaration
public Task RefreshDataAsync()
Returns
Type Description
System.Threading.Tasks.Task

System.Threading.Tasks.Task.

SearchListAsync(KeyboardEventArgs)

Task which specifies the search list.

Declaration
protected virtual Task SearchListAsync(KeyboardEventArgs arguments = null)
Parameters
Type Name Description
Microsoft.AspNetCore.Components.Web.KeyboardEventArgs arguments

Specifies the KeyboardEventArgs arguments.
Returns
Type Description
System.Threading.Tasks.Task

Task.

ShowPopupAsync()

Opens the dropdown popup that displays the list of items.

Declaration
public Task ShowPopupAsync()
Returns
Type Description
System.Threading.Tasks.Task

Task.

ShowSpinnerAsync()

Shows the data loading spinner until the data populate the pop-up.

Declaration
public Task ShowSpinnerAsync()
Returns
Type Description
System.Threading.Tasks.Task

Task.

UpdateMainData()

Task which update main data.

Declaration
protected virtual void UpdateMainData()

UpdateValueAsync()

Task which updates the value.

Declaration
protected virtual Task UpdateValueAsync()
Returns
Type Description
System.Threading.Tasks.Task

Task.

Implements

Syncfusion.Blazor.DropDowns.IVirtualList<T>