Components / AutoComplete

Blazor AutoComplete Overview

The Blazor AutoComplete component is a textbox that offers the users hints as they type. These suggestions can be filtered as the user types. The user can write their own value or click a suggestion from the dropdown to select it and populate the input. You can control the list of suggestions through data binding, various appearance settings like dimensions and templates.

Telerik UI for Blazor Ninja image

The AutoComplete component is part of Telerik UI for Blazor, a professional grade UI library with 110+ native components for building modern and feature-rich applications. To try it out sign up for a free 30-day trial.

Download Free Trial

Creating AutoComplete

  1. Use the TelerikAutoComplete tag to add the component to your razor page.
  2. Populate the Data property with the collection of items that you want to appear in the dropdown.
  3. Bind the value of the component to the same type as the member of the ValueField parameter.
  4. (Optional) Enable features like placeholder text and clear button.

AutoComplete with two-way value binding and data binding to collection of strings

@* AutoComplete with two-way value binding and data binding to a collection of strings *@

User input: @AutoCompleteValue
<br />
<TelerikAutoComplete Data="@Suggestions"
                     @bind-Value="@AutoCompleteValue"
                     Placeholder="Enter your role (can be free text)"
                     ClearButton="true" />

@code{
    //Current value is null (no item is selected) which allows the Placeholder to be displayed.
    private string AutoCompleteValue { get; set; }

    private List<string> Suggestions { get; set; } = new List<string> {
        "Manager", "Developer", "QA", "Technical Writer", "Support Engineer", "Sales Agent", "Architect", "Designer"
    };
}

If you want to get a value identifier for the items in the dropdown instead of their text, consider the ComboBox component. The AutoComplete is a free text input that accepts any text the user writes, not just the suggestions from the dropdown. Thus, the Value of the AutoComplete is always a string, while the ComboBox can provide you with a number or a Guid, not only a string.

Data Binding

The Blazor AutoComplete requires a data source so that it can populate the dropdown with data. To provide a data source, use the Data property. Read more about the Blazor AutoComplete data binding...

Filtering

The Blazor AutoComplete has a built-in filter that narrows down the shown suggestions as the end-user types. To configure this feature, use the Filterable parameter. Additionally, you can choose between different filter operators and configure after how many symbols the list with suggestions will appear. Read more about the Blazor AutoComplete filter...

Grouping

The Blazor AutoComplete enables you to group the listed suggestions into categories so you can help the end-user to browse faster through longer lists. Read more about the Blazor AutoComplete grouping...

Adornments

The component allows you to add custom elements as prefixes and suffixes. Read more about how to render custom adornments before and after the input element...

Templates

You can use the functionality of the built-in templates and customize the default rendering of the component. Read more about the Blazor AutoComplete templates...

Validation

You can ensure that the component value is acceptable by using the built-in validation. Read more about input validation....

Virtualization

By virtualizing the elements in the dropdown, you can use huge data sources without performance issues. The UI virtualization works with both local and remote data. Read more about the Blazor AutoComplete virtualization...

Adaptive Rendering

The component supports different popup rendering depending on the screen size. Read more about the Adaptive Rendering functionality and how to enable it...

AutoComplete Parameters

The Blazor AutoComplete provides various parameters that allow you to configure the component:

Parameter Type Description
AdaptiveMode AdaptiveMode
(None)		 The adaptive mode of the component.
Data IEnumerable<TItem> allows you to provide the data source. Required.
DebounceDelay int
150		 Time in milliseconds between the last typed symbol and the internal oninput event firing. Applies when the user types and filters. Use it to balance between client-side performance and number of database queries.
Enabled bool Whether the component is enabled.
Filterable bool Whether filtering is enabled for the end user (suggestions will get narrowed down as they type).
FilterOperator StringFilterOperator
(StartsWith)		 The string operation that will be used for filtering.
Id string Renders as the id attribute on the <input /> element, so you can attach a <label for=""> to the input.
LoaderShowDelay int
300		 Time in milliseconds between opening the popup and showing the loading skeleton in it when the data is not yet available.
TItem Type The type of the model to which the component is bound. Required if you can't provide Data or Value. Determines the type of the reference object.
Title string The title text rendered in the header of the popup(action sheet). Applicable only when AdaptiveMode is set to Auto.
Value and bind-Value string Get/set the value of the component, can be used for binding. Use the @bind-Value syntax for two-way binding, for example, to a variable of your own. The Value must be a string.
ValueField string
(Value)		 The name of the field from the model that will be shown as hints to the user. Not required when binding to a simple list of strings.
TabIndex int? Maps to the tabindex attribute of the HTML element. You can use it to customize the order in which the inputs in your form focus with the Tab key.
ClearButton bool Whether the user will have the option to clear the selected value with a button on the input. When it is clicked, the Value will be updated to string.Empty.
Enabled bool Use this Boolean property to render a disabled Blazor AutoComplete component until certain requirements are met.
ReadOnly bool If set to true, the component will be readonly and will not allow user input. The component is not readonly by default and allows user input.
MinLength int How many characters the text has to be before the suggestions list appears. Cannot be 0. Often works together with filtering.
Placeholder string The text the user sees as a hint when there is no text in the input. In order for it to be shown, the Value parameter should be set to the default value for string (null).

Styling and Appearance

The following parameters enable you to customize the appearance of the Blazor AutoComplete:

Parameter Type Description
Class string The CSS class that will be rendered on the main wrapping element of the component. Use it to override the theme or apply custom styles.
Width string The width of the component. It will target both the dropdown and the main element if the dropdown has no specific width set. The default Width value is null, but the theme applies 100%. Use the Width property or custom CSS to set another value in any supported unit.

You can find more options for customizing the AutoComplete styling in the Appearance article.

The AutoComplete exposes settings for its dropdown (popup). To configure the options, declare an <AutoCompletePopupSettings> tag inside the <AutoCompleteSettings> tag:

<TelerikAutoComplete Data="@AutoCompleteData"
                     @bind-Value="@SelectedItem"
                     Filterable="true"
                     FilterOperator="@StringFilterOperator.Contains"
                     Placeholder="Filter by digit or letter"
                     Width="240px">
    <AutoCompleteSettings>
        <AutoCompletePopupSettings Height="auto" MaxHeight="200px" MinHeight="75px" />
    </AutoCompleteSettings>
</TelerikAutoComplete>

@code {
    private List<string> AutoCompleteData { get; set; } = Enumerable.Range(1, 50)
        .Select(x => { return $"Item {x} {(char)Random.Shared.Next(65, 91)}{(char)Random.Shared.Next(65, 91)}"; })
        .ToList();

    private string SelectedItem { get; set; }
}

The AutoComplete provides the following popup settings:

Parameter Type Description
AnimationDuration int
(300)		 The dropdown animation duration in milliseconds.
Class string Additional CSS class to customize the appearance of the popup.
Height string
("200px")		 The height of the popup. If set to "auto", the component will automatically adjust the popup height based on the number of items and available space.
Setting MaxHeight disables the built-in screen boundary detection. This means that the component will no longer adjust the dropdown height to fit within the viewport.
MinHeight string The minimum height of the popup.
MinWidth string The minimum width of the popup.
MaxHeight string The maximum height of the popup.
MaxWidth string The maximum width of the popup.
Width string The width of the popup. If you don't specify a value, the dropdown width will match the anchor element width which can help with responsive layouts and 100% widths.

The parameters that modify the popup dimensions (Height, Width, MaxWidth, etc.) expect valid CSS values.

The MinHeight and MaxHeight have no effect if the Height is always within their range. The min and max values are useful only when the dropdown height is set to a relative unit or changes at runtime.

If the Virtualization feature is enabled, it's important to note that the auto popup width functionality doesn't work as expected. In this scenario, the dropdown popup width does not dynamically adjust based on the data items. When dealing with virtualization and long items, specifying a fixed popup Width becomes imperative. For example, set a fixed width like "300px". To determine this fixed width value, you can identify the longest item in the dropdown collection and calculate the required pixel width based on it.

If you are looking for more fields from the view-model that describes the dropdown items, not just the Value, see the Get model from dropdown KB article and the OnChange event.

You may also want to review/join the discussion and Vote for this request: Binding DropDownList Value to complex model

AutoComplete Reference and Methods

The AutoComplete is a generic component and its type is determined by the type of the model you use as its data source. You can find examples in the Data Bind - Considerations article.

Add a reference to the component instance to use the AutoComplete's methods.

Method Description
Close Closes the popup.
FocusAsync Focuses the main element of the component. Always await this call, as it relies on JSInterop. Also check the dedicated KB article about programmatic input component focusing, which provides more examples and tips.
Open Opens the popup.
Refresh Re-renders the component popup. 
<TelerikAutoComplete @ref="@AutoCompleteRef"
                     Data="@Suggestions"
                     @bind-Value="@AutoCompleteValue" 
                     Width="300px"/>

<TelerikButton OnClick="@OpenPopup">Open Popup</TelerikButton>

@code {
    private TelerikAutoComplete<string> AutoCompleteRef { get; set; }

    private string AutoCompleteValue { get; set; }

    private List<string> Suggestions { get; set; } = new List<string> { "first", "second", "third" };

    private void OpenPopup()
    {
        AutoCompleteRef.Open();

        AutoCompleteRef.Refresh();
    }
}

Next Steps

See Also

In this article
Related articles
Not finding the help you need? Improve this article