# Blazor AutoComplete Overview

The <a href="https://www.telerik.com/blazor-ui/autocomplete" target="_blank">Blazor AutoComplete component</a> is a textbox that offers the users hints as they type. These suggestions can be [filtered](https://www.telerik.com/blazor-ui/documentation/components/autocomplete/filter) 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](https://www.telerik.com/blazor-ui/documentation/components/autocomplete/data-bind), various appearance settings like [dimensions](https://www.telerik.com/blazor-ui/documentation/common-features/dimensions) and [templates](https://www.telerik.com/blazor-ui/documentation/components/autocomplete/templates).

## 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](https://www.telerik.com/blazor-ui/documentation/common-features/data-binding/overview#data-binding-vs-value-binding) to the same type as the member of the `ValueField` parameter.
4. (Optional) Enable features like placeholder text and clear button.

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

<demo metaUrl="client/autocomplete/overview/" height="250"></demo>

> tip If you want to get a value identifier for the items in the dropdown instead of their text, consider the [ComboBox component](https://www.telerik.com/blazor-ui/documentation/components/combobox/overview). 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...](https://www.telerik.com/blazor-ui/documentation/components/autocomplete/data-bind)

## 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...](https://www.telerik.com/blazor-ui/documentation/components/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...](https://www.telerik.com/blazor-ui/documentation/components/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...](https://www.telerik.com/blazor-ui/documentation/common-features/input-adornments)

## 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...](https://www.telerik.com/blazor-ui/documentation/components/autocomplete/templates)

## Validation

You can ensure that the component value is acceptable by using the built-in validation. [Read more about input validation...](https://www.telerik.com/blazor-ui/documentation/common-features/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...](https://www.telerik.com/blazor-ui/documentation/components/autocomplete/virtualization)

## Adaptive Rendering

<demo metaUrl="client/autocomplete/adaptive/" height="420"></demo>

The component supports different popup rendering depending on the screen size. [Read more about the Adaptive Rendering functionality and how to enable it...](https://www.telerik.com/blazor-ui/documentation/common-features/adaptive-rendering)

## AutoComplete Parameters

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

<style>
    .article table {
        table-layout: auto;
        word-break: normal;
    }
</style>

| Parameter                | Type                                         | Description                                                                                                                                                                                                            |
| ------------------------ | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AdaptiveMode`           | `AdaptiveMode` <br /> (`None`)               | The [adaptive mode](https://www.telerik.com/blazor-ui/documentation/common-features/adaptive-rendering) of the component.                                                                                              |
| `Data`                   | `IEnumerable<TItem>`                         | allows you to provide the data source. Required.                                                                                                                                                                       |
| `DebounceDelay`          | `int` <br/> 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](https://www.telerik.com/blazor-ui/documentation/components/multiselect/filter) is enabled for the end user (suggestions will get narrowed down as they type).                                      |
| `FilterOperator`         | `StringFilterOperator` <br /> (`StartsWith`) | The string operation that will be used for [filtering](https://www.telerik.com/blazor-ui/documentation/components/multiselect/filter).                                                                                 |
| `Id`                     | `string`                                     | Renders as the `id` attribute on the `<input />` element, so you can attach a `<label for="">` to the input.                                                                                                           |
| `InputMode`              | `string`                                     | The [`inputmode` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/inputmode) of the `<input />` element.                                                                                 |
| `LoaderShowDelay`        | `int ` <br /> 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`](https://www.telerik.com/blazor-ui/documentation/common-features/adaptive-rendering).          |
| `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` <br /> (`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.                                                                 |
| `ShowClearButton`        | `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](https://www.telerik.com/blazor-ui/documentation/components/autocomplete/filter).      |
| `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](https://www.telerik.com/blazor-ui/documentation/styling-and-themes/override-theme-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](https://www.telerik.com/blazor-ui/documentation/common-features/dimensions). |

You can find more options for customizing the AutoComplete styling in the [Appearance article](https://www.telerik.com/blazor-ui/documentation/components/autocomplete/appearance).

### Popup settings

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

<demo metaUrl="client/autocomplete/popup-settings/" height="300"></demo>

The AutoComplete provides the following popup settings:

<style>
    .article table {
        table-layout: auto;
        word-break: normal;
    }
</style>

| Parameter           | Type                        | Description                                                                                                                                                                                                                                                                                                                             |
| ------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AnimationDuration` | `int` <br /> (`300`)        | The dropdown animation duration in milliseconds.                                                                                                                                                                                                                                                                                        |
| `Class`             | `string`                    | Additional CSS class to customize the appearance of the popup.                                                                                                                                                                                                                                                                          |
| `Height`            | `string` <br /> (`"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. <br /> 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](https://www.telerik.com/blazor-ui/documentation/common-features/dimensions).

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.

> tip 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](https://www.telerik.com/blazor-ui/documentation/knowledge-base/dropdowns-get-model) KB article and the [OnChange](https://www.telerik.com/blazor-ui/documentation/components/autocomplete/events#onchange) event.
>
> You may also want to review/join the discussion and Vote for this request: <a href="https://www.telerik.com/forums/binding-dropdownlist-value-to-complex-model" target="_blank">Binding DropDownList Value to complex model</a>

## AutoComplete Reference and Methods

Add a reference to the component instance to use the [AutoComplete's methods](https://www.telerik.com/blazor-ui/documentation/api/telerik.blazor.components.telerikautocomplete-1). Note that the [AutoComplete is a generic component](https://www.telerik.com/blazor-ui/documentation/common-features/data-binding/overview#component-type).

<style>
    .article table {
        table-layout: auto;
        word-break: normal;
    }
</style>

| 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](https://www.telerik.com/blazor-ui/documentation/knowledge-base/inputs-set-focus), which provides more examples and tips. |
| `Open`       | Opens the popup.                                                                                                                                                                                                                                                                                             |
| `Refresh`    | Re-renders the component popup.                                                                                                                                                                                                                                                                              |

<demo metaUrl="client/autocomplete/methods/" height="250"></demo>

## Next Steps

* [Binding the AutoComplete to Data](https://www.telerik.com/blazor-ui/documentation/components/autocomplete/data-bind)

## See Also

* [Data Binding](https://www.telerik.com/blazor-ui/documentation/components/autocomplete/data-bind)
* [Live Demo: AutoComplete](https://demos.telerik.com/blazor-ui/autocomplete/overview)
* [Live Demo: AutoComplete Validation](https://demos.telerik.com/blazor-ui/autocomplete/validation)
* [AutoComplete API Reference](https://www.telerik.com/blazor-ui/documentation/api/telerik.blazor.components.telerikautocomplete-1)
