Class SfAutoComplete<TValue, TItem>
The SfAutoComplete<TValue, TItem> component provides a matched suggestion list when typing into the input, allowing users to select an item.
Inheritance
Implements
Inherited Members
Namespace: Syncfusion.Blazor.DropDowns
Assembly: Syncfusion.Blazor.dll
Syntax
public class SfAutoComplete<TValue, TItem> : SfComboBox<TValue, TItem>, IInputBase, IDropDowns, IVirtualList<TItem>Type Parameters
| Name |
|---|
| TValue |
| TItem |
Constructors
SfAutoComplete()
Declaration
public SfAutoComplete()Properties
FilterType
Gets or sets the type of filtering applied to the SfAutoComplete<TValue, TItem> items.
Declaration
public override FilterType FilterType { get; set; }Property Value
| Type | Description |
|---|---|
| FilterType | A FilterType value specifying the filtering mode. The default value is Contains. |
Overrides
Remarks
This property determines how the AutoComplete filters the suggestion list based on user input, such as StartsWith, Contains, or EndsWith.
Examples
<SfAutoComplete TItem="string" TValue="string" FilterType="FilterType.StartsWith" DataSource="@MyList">
</SfAutoComplete>
@code {
protected List<string> MyList = new List<string>() { "Small", "Medium", "Large" };
}Highlight
Gets or sets a value indicating whether the searched characters in the suggestion list should highlight matched portions of the text.
Declaration
public bool Highlight { get; set; }Property Value
| Type | Description |
|---|---|
| System.Boolean | A System.Boolean indicating whether to highlight matched text. The default value is |
Remarks
When set to true, the characters in the suggestion list that match the user's input are visually highlighted, improving the user experience by making matches more noticeable.
Examples
<SfAutoComplete TItem="string" TValue="string" Highlight="true" DataSource="@MyList">
</SfAutoComplete>
@code {
protected List<string> MyList = new List<string>() { "Small", "Medium", "Large" };
}MinLength
Gets or sets the minimum number of characters required to trigger the search for suggestions.
Declaration
public int MinLength { get; set; }Property Value
| Type | Description |
|---|---|
| System.Int32 | An System.Int32 representing the minimum number of characters needed to initiate a search. The default value is |
Remarks
This property controls when the AutoComplete starts filtering suggestions based on user input. A higher value can improve performance by reducing unnecessary searches.
Examples
<SfAutoComplete TItem="string" TValue="string" MinLength="2" DataSource="@MyList">
</SfAutoComplete>
@code {
protected List<string> MyList = new List<string>() { "Small", "Medium", "Large" };
}ShowClearButton
Gets or sets a value indicating whether the clear button is displayed to reset the selected value.
Declaration
public override bool ShowClearButton { get; set; }Property Value
| Type | Description |
|---|---|
| System.Boolean | A System.Boolean indicating whether the clear button is visible. The default value is |
Overrides
Remarks
When the clear button is clicked, the Value and Index properties are reset to null, allowing users to clear the selected value and start fresh.
Examples
<SfAutoComplete TItem="string" TValue="string" ShowClearButton="true" DataSource="@MyList">
</SfAutoComplete>
@code {
protected List<string> MyList = new List<string>() { "Small", "Medium", "Large" };
}ShowPopupButton
Gets or sets a value indicating whether the popup button is displayed in the SfAutoComplete<TValue, TItem> component.
Declaration
public bool ShowPopupButton { get; set; }Property Value
| Type | Description |
|---|---|
| System.Boolean | A System.Boolean indicating whether the popup button is visible. The default value is |
Remarks
When set to true, a popup button is displayed, allowing users to manually open the suggestion list. This enhances the user experience by providing an explicit way to view suggestions.
Examples
<SfAutoComplete TItem="string" TValue="string" ShowPopupButton="true" DataSource="@MyList">
</SfAutoComplete>
@code {
protected List<string> MyList = new List<string>() { "Small", "Medium", "Large" };
}SuggestionCount
Gets or sets the maximum number of suggestions displayed in the SfAutoComplete<TValue, TItem> dropdown.
Declaration
public int SuggestionCount { get; set; }Property Value
| Type | Description |
|---|---|
| System.Int32 | An System.Int32 representing the maximum number of items shown in the suggestion list. The default value is |
Remarks
This property limits the number of suggestions displayed in the dropdown, improving performance and user experience when dealing with large data sets.
Examples
<SfAutoComplete TItem="string" TValue="string" SuggestionCount="10" DataSource="@MyList">
</SfAutoComplete>
@code {
protected List<string> MyList = new List<string>() { "Small", "Medium", "Large" };
}Methods
ActionBeginAsync(IEnumerable<TItem>, Query)
Triggers the action begin event for the SfAutoComplete<TValue, TItem> component.
Declaration
protected override Task<ActionBeginEventArgs> ActionBeginAsync(IEnumerable<TItem> dataSource, Query query = null)Parameters
| Type | Name | Description |
|---|---|---|
| System.Collections.Generic.IEnumerable<TItem> | dataSource | The data source for the suggestion list. |
| Query | query | The query used to fetch the data. |
Returns
| Type | Description |
|---|---|
| System.Threading.Tasks.Task<ActionBeginEventArgs> | A System.Threading.Tasks.Task that returns an ActionBeginEventArgs object. |
Overrides
Remarks
This method is called before fetching data, invoking the OnActionBegin event and displaying a spinner to indicate loading.
Exceptions
| Type | Condition |
|---|---|
| System.Exception | Thrown if an error occurs during the event invocation. |
ActionCompleteAsync(IEnumerable<TItem>, Query)
Triggers the action complete event for the SfAutoComplete<TValue, TItem> component.
Declaration
protected override Task ActionCompleteAsync(IEnumerable<TItem> dataSource, Query query = null)Parameters
| Type | Name | Description |
|---|---|---|
| System.Collections.Generic.IEnumerable<TItem> | dataSource | The data source containing the fetched items. |
| Query | query | The query used to fetch the data. |
Returns
| Type | Description |
|---|---|
| System.Threading.Tasks.Task | A System.Threading.Tasks.Task representing the asynchronous operation. |
Overrides
Remarks
This method is called after data is successfully fetched, invoking the OnActionComplete and DataBound events, rendering the items, and handling autofill if enabled.
Exceptions
| Type | Condition |
|---|---|
| System.Exception | Thrown if an error occurs during the event invocation or rendering. |
ActionFailureAsync(Object)
Triggers the action failure event for the SfAutoComplete<TValue, TItem> component.
Declaration
protected override Task ActionFailureAsync(object arguments)Parameters
| Type | Name | Description |
|---|---|---|
| System.Object | arguments | The object representing the error that occurred. |
Returns
| Type | Description |
|---|---|
| System.Threading.Tasks.Task | A System.Threading.Tasks.Task representing the asynchronous operation. |
Overrides
Remarks
This method is called when a data fetch operation fails, invoking the OnActionFailure event and creating the popup if necessary.
Exceptions
| Type | Condition |
|---|---|
| System.Exception | Thrown if an error occurs during the event invocation. |
BuildRenderTree(RenderTreeBuilder)
Declaration
protected override void BuildRenderTree(RenderTreeBuilder __builder)Parameters
| Type | Name | Description |
|---|---|---|
| Microsoft.AspNetCore.Components.Rendering.RenderTreeBuilder | __builder |
Overrides
ClearAllAsync(EventArgs, Boolean)
Clears all selected values and resets the SfAutoComplete<TValue, TItem> component.
Declaration
protected override Task ClearAllAsync(EventArgs arguments = null, bool IsProgrammaticallyCleared = false)Parameters
| Type | Name | Description |
|---|---|---|
| System.EventArgs | arguments | The event arguments associated with the clear action. |
| System.Boolean | IsProgrammaticallyCleared | A boolean indicating whether the clear action was triggered programmatically. |
Returns
| Type | Description |
|---|---|
| System.Threading.Tasks.Task | A System.Threading.Tasks.Task representing the asynchronous operation. |
Overrides
Remarks
This method clears the selected value, resets the input, and hides the suggestion popup if it is open, while also focusing the input field.
Exceptions
| Type | Condition |
|---|---|
| System.Exception | Thrown if an error occurs during the clear operation. |
FocusHandlerAsync(FocusEventArgs)
Handles the focus-in event for the component.
Declaration
protected override Task FocusHandlerAsync(FocusEventArgs arguments)Parameters
| Type | Name | Description |
|---|---|---|
| Microsoft.AspNetCore.Components.Web.FocusEventArgs | arguments | The focus event arguments. |
Returns
| Type | Description |
|---|---|
| System.Threading.Tasks.Task | A System.Threading.Tasks.Task representing the asynchronous operation. |
Overrides
Remarks
This method is called when the component gains focus, invoking the Focus event and updating the component's visual state.
Exceptions
| Type | Condition |
|---|---|
| System.Exception | Thrown if an error occurs during the focus handling. |
GetQuery(Query)
Constructs the query for filtering the suggestion list.
Declaration
protected override Query GetQuery(Query query)Parameters
| Type | Name | Description |
|---|---|---|
| Query | query | The query to modify or use as a base. |
Returns
| Type | Description |
|---|---|
| Query | A Query object representing the constructed query. |
Overrides
Remarks
This method builds a query for filtering the suggestion list based on the current input, field settings, and filter type, applying limits such as SuggestionCount and virtualization settings.
Exceptions
| Type | Condition |
|---|---|
| System.Exception | Thrown if an error occurs during query construction. |
HighLightSearch(String, Boolean, FilterType, String)
Highlights the searched characters in the suggestion list items.
Declaration
public string HighLightSearch(string textValue, bool ignoreCase, FilterType filtertype, string highLighText = null)Parameters
| Type | Name | Description |
|---|---|---|
| System.String | textValue | The text value to highlight in the list item. |
| System.Boolean | ignoreCase | A boolean indicating whether to perform a case-insensitive search. |
| FilterType | filtertype | The FilterType that determines how the highlight is applied (e.g., StartsWith, Contains, EndsWith). |
| System.String | highLighText | An optional string to highlight instead of the filter input value. |
Returns
| Type | Description |
|---|---|
| System.String | A System.String containing the text with highlighted portions. |
Remarks
This method formats the specified text by highlighting the portions that match the search criteria, based on the provided filter type and case sensitivity.
Examples
<SfAutoComplete TItem="string" TValue="string" DataSource="@MyList">
</SfAutoComplete>
@code {
protected List<string> MyList = new List<string>() { "Small", "Medium", "Large" };
public string HighlightText(string text) {
return AutoCompleteObj.HighLightSearch(text, true, FilterType.Contains);
}
}Exceptions
| Type | Condition |
|---|---|
| System.ArgumentNullException | Thrown if |
InvokeBlurEventAsync()
Invokes the blur event for the component.
Declaration
protected override Task InvokeBlurEventAsync()Returns
| Type | Description |
|---|---|
| System.Threading.Tasks.Task | A System.Threading.Tasks.Task representing the asynchronous operation. |
Overrides
Remarks
This method is called when the component loses focus, invoking the Blur event unless the focus loss was triggered by a clear button click.
Exceptions
| Type | Condition |
|---|---|
| System.Exception | Thrown if an error occurs during the blur event invocation. |
InvokeChangeEventAsync(EventArgs, KeyActions)
Invokes the change event for the component.
Declaration
protected override Task InvokeChangeEventAsync(EventArgs arguments = null, KeyActions keyActionArguments = null)Parameters
| Type | Name | Description |
|---|---|---|
| System.EventArgs | arguments | The event arguments associated with the change. |
| KeyActions | keyActionArguments | The key action arguments, if triggered by keyboard navigation. |
Returns
| Type | Description |
|---|---|
| System.Threading.Tasks.Task | A System.Threading.Tasks.Task representing the asynchronous operation. |
Overrides
Remarks
This method is called when the Value property changes, invoking the ValueChange event with details about the new and previous values.
Exceptions
| Type | Condition |
|---|---|
| System.Exception | Thrown if an error occurs during the event invocation. |
InvokeClosedEventAsync()
Triggers after the suggestion popup is closed.
Declaration
protected override Task<ClosedEventArgs> InvokeClosedEventAsync()Returns
| Type | Description |
|---|---|
| System.Threading.Tasks.Task<ClosedEventArgs> | A System.Threading.Tasks.Task that returns a ClosedEventArgs object. |
Overrides
Remarks
This method is called after the suggestion popup is closed, performing cleanup tasks such as removing autofill selection and invoking the Closed event.
Exceptions
| Type | Condition |
|---|---|
| System.Exception | Thrown if an error occurs during the event invocation. |
InvokeCustomValueEventAsync()
Triggers the custom value event for the SfAutoComplete<TValue, TItem> component.
Declaration
protected override Task<CustomValueSpecifierEventArgs<TItem>> InvokeCustomValueEventAsync()Returns
| Type | Description |
|---|---|
| System.Threading.Tasks.Task<CustomValueSpecifierEventArgs<TItem>> | A System.Threading.Tasks.Task that returns a CustomValueSpecifierEventArgs<T> object. |
Overrides
Remarks
This method is called when a custom value is entered, invoking the CustomValueSpecifier event to handle custom input processing.
Exceptions
| Type | Condition |
|---|---|
| System.Exception | Thrown if an error occurs during the event invocation. |
InvokeOpenEventAsync()
Triggers before the suggestion popup is opened.
Declaration
protected override Task<BeforeOpenEventArgs> InvokeOpenEventAsync()Returns
| Type | Description |
|---|---|
| System.Threading.Tasks.Task<BeforeOpenEventArgs> | A System.Threading.Tasks.Task that returns a BeforeOpenEventArgs object indicating whether the popup opening is canceled. |
Overrides
Remarks
This method is called before the suggestion popup is displayed, allowing cancellation of the popup opening via the BeforeOpenEventArgs.Cancel property.
Exceptions
| Type | Condition |
|---|---|
| System.Exception | Thrown if an error occurs during the event invocation. |
InvokePopupEventsAsync(Boolean)
Invokes popup-related events for the component.
Declaration
protected override Task<PopupEventArgs> InvokePopupEventsAsync(bool isOpen)Parameters
| Type | Name | Description |
|---|---|---|
| System.Boolean | isOpen | A boolean indicating whether the popup is in the open state. |
Returns
| Type | Description |
|---|---|
| System.Threading.Tasks.Task<PopupEventArgs> | A System.Threading.Tasks.Task that returns a PopupEventArgs object. |
Overrides
Remarks
This method is called when the suggestion popup opens or closes, invoking the Opened or OnClose events as appropriate.
Exceptions
| Type | Condition |
|---|---|
| System.Exception | Thrown if an error occurs during the event invocation. |
InvokeSelectEventAsync(TItem, EventArgs, KeyActions)
Returns the event arguments for item selection in the component.
Declaration
protected override Task<SelectEventArgs<TItem>> InvokeSelectEventAsync(TItem item, EventArgs arguments = null, KeyActions keyActionsArguments = null)Parameters
| Type | Name | Description |
|---|---|---|
| TItem | item | The selected item from the suggestion list. |
| System.EventArgs | arguments | The event arguments associated with the selection. |
| KeyActions | keyActionsArguments | The key action arguments, if triggered by keyboard navigation. |
Returns
| Type | Description |
|---|---|
| System.Threading.Tasks.Task<SelectEventArgs<TItem>> | A System.Threading.Tasks.Task that returns a SelectEventArgs<T> object. |
Overrides
Remarks
This method is called when an item is selected, invoking the OnValueSelect event and updating the input value if necessary.
Exceptions
| Type | Condition |
|---|---|
| System.Exception | Thrown if an error occurs during the event invocation. |
IsAutoFillEnabled()
Determines whether autofill is enabled for the component.
Declaration
protected override bool IsAutoFillEnabled()Returns
| Type | Description |
|---|---|
| System.Boolean | A System.Boolean indicating whether autofill is enabled. |
Overrides
Remarks
This method returns the value of the Autofill property, indicating whether the component automatically fills the input with the first matching suggestion.
IsEditableInput()
Determines whether the input in the component is editable.
Declaration
protected override bool IsEditableInput()Returns
| Type | Description |
|---|---|
| System.Boolean | A System.Boolean indicating whether the input is editable. |
Overrides
Remarks
This method checks if the input contains non-empty text, indicating that the user can edit the input field.
IsFilterMode()
Determines whether the filter mode is enabled for the component.
Declaration
protected override bool IsFilterMode()Returns
| Type | Description |
|---|---|
| System.Boolean | A System.Boolean indicating whether filter mode is enabled. Always returns |
Overrides
Remarks
This method indicates that the AutoComplete component operates in filter mode, allowing users to filter the suggestion list based on their input.
ListItemCreated(ListOptions<TItem>)
Processes a list item before it is rendered in the suggestion list.
Declaration
protected override ListOptions<TItem> ListItemCreated(ListOptions<TItem> listItem)Parameters
| Type | Name | Description |
|---|---|---|
| ListOptions<TItem> | listItem | The list item to process. |
Returns
| Type | Description |
|---|---|
| ListOptions<TItem> | A ListOptions<T> object representing the processed list item. |
Overrides
Remarks
This method applies highlighting to the list item text if the Highlight property is enabled and the component is in a typed state.
OnAfterRenderAsync(Boolean)
Triggers after the component is rendered.
Declaration
protected override Task OnAfterRenderAsync(bool firstRender)Parameters
| Type | Name | Description |
|---|---|---|
| System.Boolean | firstRender | A boolean indicating whether this is the first render of the component. |
Returns
| Type | Description |
|---|---|
| System.Threading.Tasks.Task | A System.Threading.Tasks.Task representing the asynchronous operation. |
Overrides
Remarks
This method is called after the component is rendered, handling tasks such as invoking the Created event and updating the InPlaceEditor if applicable.
Exceptions
| Type | Condition |
|---|---|
| System.Exception | Thrown if an error occurs during the rendering process. |
OnInitializedAsync()
Triggers during the initial rendering of this component.
Declaration
protected override Task OnInitializedAsync()Returns
| Type | Description |
|---|---|
| System.Threading.Tasks.Task | A System.Threading.Tasks.Task representing the asynchronous initialization operation. |
Overrides
Remarks
This method is called when the component is first initialized, setting up the component's ID and linking to the parent InPlaceEditor if applicable.
Exceptions
| Type | Condition |
|---|---|
| System.Exception | Thrown if an error occurs during initialization. |
SearchListAsync(KeyboardEventArgs, Boolean)
Performs a search operation on the suggestion list.
Declaration
protected override Task SearchListAsync(KeyboardEventArgs arguments = null, bool isTabAction = false)Parameters
| Type | Name | Description |
|---|---|---|
| Microsoft.AspNetCore.Components.Web.KeyboardEventArgs | arguments | The keyboard event arguments, if triggered by a key press. |
| System.Boolean | isTabAction | A boolean indicating whether the action was triggered by the Tab key. |
Returns
| Type | Description |
|---|---|
| System.Threading.Tasks.Task | A System.Threading.Tasks.Task representing the asynchronous search operation. |
Overrides
Remarks
This method handles the filtering of the suggestion list based on user input, invoking the Filtering event and performing the search if not canceled.
Exceptions
| Type | Condition |
|---|---|
| System.Exception | Thrown if an error occurs during the search operation. |
UpdateFocusItemAsync(TItem)
Updates the focused item in the suggestion list.
Declaration
protected override Task UpdateFocusItemAsync(TItem focusedItem = null)Parameters
| Type | Name | Description |
|---|---|---|
| TItem | focusedItem | The item to focus in the suggestion list. |
Returns
| Type | Description |
|---|---|
| System.Threading.Tasks.Task | A System.Threading.Tasks.Task representing the asynchronous operation. |
Overrides
Remarks
This method updates the visual focus state of an item in the suggestion list when the component is rendering the list and the input is active.
Exceptions
| Type | Condition |
|---|---|
| System.Exception | Thrown if an error occurs during the focus update. |
UpdateMainData()
Updates the main data source for the SfAutoComplete<TValue, TItem> component.
Declaration
protected override void UpdateMainData()Overrides
Remarks
This method synchronizes the main data source with the current list data, ensuring consistency in the suggestion list.