Class SfDropDownList<TValue, TItem>
The DropDownList component allows users to select a single value that is non-editable from a list of predefined values.
Implements
Inherited Members
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 |
---|
System.String |
BOTH
Declaration
protected const string BOTH = "both"
Field Value
Type |
---|
System.String |
FALSE
Specifies the string false.
Declaration
protected const string FALSE = "false"
Field Value
Type |
---|
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 |
---|
System.String |
TRUE
Specifies the string true.
Declaration
protected const string TRUE = "true"
Field Value
Type |
---|
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 |
|
Remarks
The filter action retrieves the matched items using the Filtering event based on the characters typed in the search textbox.
AllowResize
Gets or sets a value indicating whether the resizing option is enabled for the dropdown popup.
Declaration
public bool AllowResize { get; set; }
Property Value
Type | Description |
---|---|
System.Boolean |
|
Remarks
When AllowResize
is set to true
, the dropdown popup includes a resizable handle at the bottom right corner, enabling users to adjust its size.
This resizing functionality can be further controlled using the OnResizeStart, OnResizing, and OnResizeStop events to monitor or restrict resizing behavior.
Examples
@code {
private void HandleResizeStart(object args) {
Console.WriteLine("Resize started.");
}
private void HandleResizing(object args) {
Console.WriteLine("Resizing...");
}
private void HandleResizeStop(object args) {
Console.WriteLine("Resize stopped.");
}
}
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 |
DebounceDelay
Gets or sets the debounce delay in milliseconds for filtering the items in the SfDropDownList<TValue, TItem> component. The debounce delay represents the time delay between the last keystroke and the filtering operation. This delay helps reduce the frequency of data filtering while typing. The default value is 300 milliseconds.
The DebounceDelay property only takes effect when the AllowFiltering property is set to true
.
Declaration
public int DebounceDelay { get; set; }
Property Value
Type | Description |
---|---|
System.Int32 | An integer representing the debounce delay in milliseconds. The default value is 300. |
Remarks
The DebounceDelay property helps optimize performance by delaying the filtering operation
until the user has stopped typing for the specified delay duration.
To work with the default filtering scenario, the user needs to set the DebounceDelay
value to zero.
Examples
The following example demonstrates how to set the DebounceDelay property to 500 milliseconds.
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 |
|
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 |
|
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 |
|
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 |
|
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 |
Remarks
This property value is updated only when the AllowFiltering is enabled.
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 |
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 |
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 |
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 |
Remarks
You can specify only unique value.
IncrementalListData
Declaration
protected IEnumerable<TItem> IncrementalListData { get; set; }
Property Value
Type |
---|
System.Collections.Generic.IEnumerable<TItem> |
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 |
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 |
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 |
---|
System.Boolean |
IsComboBox
Declaration
protected bool IsComboBox { get; set; }
Property Value
Type |
---|
System.Boolean |
IsDropDownList
Declaration
protected bool IsDropDownList { get; set; }
Property Value
Type |
---|
System.Boolean |
IsIncrementalRequest
Declaration
protected bool IsIncrementalRequest { get; set; }
Property Value
Type |
---|
System.Boolean |
IsPopupShown
Declaration
protected bool IsPopupShown { get; set; }
Property Value
Type |
---|
System.Boolean |
IsTabKeyAction
Declaration
protected bool IsTabKeyAction { get; set; }
Property Value
Type |
---|
System.Boolean |
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 |
Remarks
The property depends on the FloatLabelType property, The placeholder text acts as a label.
PopupDisplayMode
Gets or sets the display mode of the dropdown popup on mobile devices.
Declaration
public PopupDisplayMode PopupDisplayMode { get; set; }
Property Value
Type | Description |
---|---|
PopupDisplayMode | The default value is FullScreen. |
Remarks
The PopupDisplayMode enum has two possible values:
- FullScreen: The popup opens in fullscreen mode on mobile devices when filtering is enabled. This is applicable for both SfDropDownList<TValue, TItem> and SfMultiSelect<TValue, TItem> components in checkbox mode with filtering enabled.
- Inline: The popup opens similarly on both mobile and desktop devices, above the input field without fullscreen mode.
Examples
The following example demonstrates how to use the PopupDisplayMode property:
DropdownList with PopupDisplayMode set to Inline
<SfDropdownList TValue="string" DataSource="@Data" PopupDisplayMode="PopupDisplayMode.Inline">
<DropDownListFieldSettings Text="Text" Value="Id"></DropDownListFieldSettings>
</SfDropdownList>
@code {
public List<DropDownData> Data { get; set; } = new List<DropDownData>
{
new DropDownData { Id = "1", Text = "Option 1" },
new DropDownData { Id = "2", Text = "Option 2" },
new DropDownData { Id = "3", Text = "Option 3" }
};
public class DropDownData
{
public string Id { get; set; }
public string Text { get; set; }
}
}
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 |
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 |
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 |
|
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 |
|
Remarks
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 |
TokenSource
Declaration
protected CancellationTokenSource TokenSource { get; set; }
Property Value
Type |
---|
System.Threading.CancellationTokenSource |
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 |
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 |
---|
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 |
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 |
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. |
DisableItem(TValue)
Method to disable a specific item in the popup using its TValue.
Declaration
public Task DisableItem(TValue item)
Parameters
Type | Name | Description |
---|---|---|
TValue | item | The value or index of the item to be disabled. |
Returns
Type |
---|
System.Threading.Tasks.Task |
Remarks
This method disables a specific item in the popup based on the provided item
.
If the item is of type TValue
, it represents the value associated with the item.
DisableItem(Int32)
Method to disable a specific item in the popup based on its index position.
Declaration
public Task DisableItem(int item)
Parameters
Type | Name | Description |
---|---|---|
System.Int32 | item | The value or index of the item to be disabled. |
Returns
Type |
---|
System.Threading.Tasks.Task |
Remarks
This method disables a specific item in the popup based on the provided item
.
If the item is of type System.Int32, it represents the index of the item in the popup.
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. |
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. |
SetCurrentViewDataAsync(Int32, Int32)
Declaration
protected override Task SetCurrentViewDataAsync(int virtualItemStartIndex, int virtualItemEndIndex)
Parameters
Type | Name | Description |
---|---|---|
System.Int32 | virtualItemStartIndex | |
System.Int32 | virtualItemEndIndex |
Returns
Type |
---|
System.Threading.Tasks.Task |
Overrides
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. |
UpdateDisableItem(TItem)
Updates the disabled status of a given item in the list.
Declaration
protected void UpdateDisableItem(TItem itemData)
Parameters
Type | Name | Description |
---|---|---|
TItem | itemData | The item to be updated. |
Remarks
This method checks if the given item is not null and if it's not disabled. If so, it sets the disabled field of the item to true. It then updates the item in the ListData and disables the corresponding list item in the ListDataSource. If the item to be disabled is currently selected, it updates the value selection asynchronously.
UpdateIncrementalInfo(Int32, Int32, Boolean)
Declaration
protected Task UpdateIncrementalInfo(int startIndex, int endIndex, bool isIncremental = true)
Parameters
Type | Name | Description |
---|---|---|
System.Int32 | startIndex | |
System.Int32 | endIndex | |
System.Boolean | isIncremental |
Returns
Type |
---|
System.Threading.Tasks.Task |
UpdateIncrementalItemIndex(Int32, Int32)
Declaration
protected void UpdateIncrementalItemIndex(int startIndex, int endIndex)
Parameters
Type | Name | Description |
---|---|---|
System.Int32 | startIndex | |
System.Int32 | endIndex |
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. |