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
object
ComponentBase
OwningComponentBase
SfOwningComponentBase
SfBaseComponent
SfDataBoundComponent
SfDropDownBase<TItem>
SfDropDownList<TValue, TItem>
SfComboBox<TValue, TItem>
SfAutoComplete<TValue, TItem>
Implements
Inherited Members
Namespace: Syncfusion.Blazor.DropDowns
Assembly: Syncfusion.Blazor.dll
Syntax
public class SfAutoComplete<TValue, TItem> : SfComboBox<TValue, TItem>, IComponent, IHandleEvent, IHandleAfterRender, IDisposable
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
[Parameter]
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
[Parameter]
public bool Highlight { get; set; }
Property Value
Type Description
bool

A bool indicating whether to highlight matched text. The default value is false.
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
[Parameter]
public int MinLength { get; set; }
Property Value
Type Description
int

An int representing the minimum number of characters needed to initiate a search. The default value is 1.
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
[Parameter]
public override bool ShowClearButton { get; set; }
Property Value
Type Description
bool

A bool indicating whether the clear button is visible. The default value is true.
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
[Parameter]
public bool ShowPopupButton { get; set; }
Property Value
Type Description
bool

A bool indicating whether the popup button is visible. The default value is false.
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
[Parameter]
public int SuggestionCount { get; set; }
Property Value
Type Description
int

An int representing the maximum number of items shown in the suggestion list. The default value is 20.
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
IEnumerable<TItem> dataSource

The data source for the suggestion list.
Query query

The query used to fetch the data.
Returns
Type Description
Task<ActionBeginEventArgs>

A 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
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
IEnumerable<TItem> dataSource

The data source containing the fetched items.
Query query

The query used to fetch the data.
Returns
Type Description
Task

A 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
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
object arguments

The object representing the error that occurred.
Returns
Type Description
Task

A 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
Exception

Thrown if an error occurs during the event invocation.

BuildRenderTree(RenderTreeBuilder)

Declaration
protected override void BuildRenderTree(RenderTreeBuilder __builder)
Parameters
Type Name Description
RenderTreeBuilder __builder
Overrides

ClearAllAsync(EventArgs?, bool)

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
EventArgs arguments

The event arguments associated with the clear action.
bool IsProgrammaticallyCleared

A boolean indicating whether the clear action was triggered programmatically.
Returns
Type Description
Task

A 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
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
FocusEventArgs arguments

The focus event arguments.
Returns
Type Description
Task

A 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
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
Exception

Thrown if an error occurs during query construction.

HighLightSearch(string, bool, 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
string textValue

The text value to highlight in the list item.
bool 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).
string highLighText

An optional string to highlight instead of the filter input value.
Returns
Type Description
string

A 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
ArgumentNullException

Thrown if textValue is null.

InvokeBlurEventAsync()

Invokes the blur event for the component.

Declaration
protected override Task InvokeBlurEventAsync()
Returns
Type Description
Task

A Task representing the asynchronous operation.
Overrides
Syncfusion.Blazor.DropDowns.SfComboBox<TValue, TItem>.InvokeBlurEventAsync()
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
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
EventArgs arguments

The event arguments associated with the change.
KeyActions keyActionArguments

The key action arguments, if triggered by keyboard navigation.
Returns
Type Description
Task

A 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
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
Task<ClosedEventArgs>

A Task that returns a ClosedEventArgs object.
Overrides
Syncfusion.Blazor.DropDowns.SfComboBox<TValue, TItem>.InvokeClosedEventAsync()
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
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
Task<CustomValueSpecifierEventArgs<TItem>>

A Task that returns a CustomValueSpecifierEventArgs<T> object.
Overrides
Syncfusion.Blazor.DropDowns.SfComboBox<TValue, TItem>.InvokeCustomValueEventAsync()
Remarks

This method is called when a custom value is entered, invoking the CustomValueSpecifier event to handle custom input processing.

Exceptions
Type Condition
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
Task<BeforeOpenEventArgs>

A Task that returns a BeforeOpenEventArgs object indicating whether the popup opening is canceled.
Overrides
Syncfusion.Blazor.DropDowns.SfComboBox<TValue, TItem>.InvokeOpenEventAsync()
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
Exception

Thrown if an error occurs during the event invocation.

InvokePopupEventsAsync(bool)

Invokes popup-related events for the component.

Declaration
protected override Task<PopupEventArgs> InvokePopupEventsAsync(bool isOpen)
Parameters
Type Name Description
bool isOpen

A boolean indicating whether the popup is in the open state.
Returns
Type Description
Task<PopupEventArgs>

A 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
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.
EventArgs arguments

The event arguments associated with the selection.
KeyActions keyActionsArguments

The key action arguments, if triggered by keyboard navigation.
Returns
Type Description
Task<SelectEventArgs<TItem>>

A 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
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
bool

A bool indicating whether autofill is enabled.
Overrides
Syncfusion.Blazor.DropDowns.SfComboBox<TValue, TItem>.IsAutoFillEnabled()
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
bool

A bool indicating whether the input is editable.
Overrides
Syncfusion.Blazor.DropDowns.SfDropDownList<TValue, TItem>.IsEditableInput()
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
bool

A bool indicating whether filter mode is enabled. Always returns true.
Overrides
Syncfusion.Blazor.DropDowns.SfComboBox<TValue, TItem>.IsFilterMode()
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(bool)

Triggers after the component is rendered.

Declaration
protected override Task OnAfterRenderAsync(bool firstRender)
Parameters
Type Name Description
bool firstRender

A boolean indicating whether this is the first render of the component.
Returns
Type Description
Task

A 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
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
Task

A Task representing the asynchronous initialization operation.
Overrides
Syncfusion.Blazor.DropDowns.SfComboBox<TValue, TItem>.OnInitializedAsync()
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
Exception

Thrown if an error occurs during initialization.

SearchListAsync(KeyboardEventArgs, bool)

Performs a search operation on the suggestion list.

Declaration
protected override Task SearchListAsync(KeyboardEventArgs arguments = null, bool isTabAction = false)
Parameters
Type Name Description
KeyboardEventArgs arguments

The keyboard event arguments, if triggered by a key press.
bool isTabAction

A boolean indicating whether the action was triggered by the Tab key.
Returns
Type Description
Task

A 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
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 = default)
Parameters
Type Name Description
TItem focusedItem

The item to focus in the suggestion list.
Returns
Type Description
Task

A Task representing the asynchronous operation.
Overrides
Syncfusion.Blazor.DropDowns.SfDropDownList<TValue, TItem>.UpdateFocusItemAsync(TItem)
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
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
Syncfusion.Blazor.DropDowns.SfComboBox<TValue, TItem>.UpdateMainData()
Remarks

This method synchronizes the main data source with the current list data, ensuring consistency in the suggestion list.

Implements