# Blazor ComboBox Overview

The <a href="https://www.telerik.com/blazor-ui/combobox" target="_blank">Blazor ComboBox component</a> allows the user to choose an option from a predefined set of choices presented in a dropdown popup. You can also allow them to enter [custom values](https://www.telerik.com/blazor-ui/documentation/components/combobox/custom-value) and to [filter](https://www.telerik.com/blazor-ui/documentation/components/combobox/filter) the available items. You can control the [data](https://www.telerik.com/blazor-ui/documentation/components/dropdownlist/data-bind), sizes, and various appearance options like class and [templates](https://www.telerik.com/blazor-ui/documentation/components/combobox/templates).

## Creating Blazor ComboBox

1. Use the `TelerikComboBox` 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. Set the `TextField` and `ValueField` properties to point to the corresponding names of the model
4. [Bind the value of the component](https://www.telerik.com/blazor-ui/documentation/common-features/data-binding/overview#data-binding-vs-value-binding) to a variable of the same type as the type defined in the `ValueField` parameter.
5. (optional) enable features like filtering and clear button

> caption Combobox [data binding](https://www.telerik.com/blazor-ui/documentation/components/combobox/data-bind) with two-way value binding

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

## Data Binding

The Blazor ComboBox 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 ComboBox data binding...](https://www.telerik.com/blazor-ui/documentation/components/combobox/data-bind).

## Filtering

The Blazor ComboBox 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 ComboBox filter...](https://www.telerik.com/blazor-ui/documentation/components/combobox/filter).

## Grouping

The Blazor ComboBox 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 ComboBox grouping...](https://www.telerik.com/blazor-ui/documentation/components/combobox/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 ComboBox templates...](https://www.telerik.com/blazor-ui/documentation/components/combobox/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 ComboBox virtualization...](https://www.telerik.com/blazor-ui/documentation/components/combobox/virtualization)

## Adaptive Rendering

<demo metaUrl="client/combobox/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)

## Parameters

> caption The Blazor ComboBox 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.                                                                                                                                                                                                                                                                                                                    |
| `AllowCustom`            | `bool`                                       | Defines if the user can enter a custom value that is not among the dropdown items. The custom user input becomes the component `Value`. If enabled, the `Value` must be of type `string`. See [ComboBox Custom Values](https://www.telerik.com/blazor-ui/documentation/components/combobox/custom-value) for details and examples.                                                                                                           |
| `ShowClearButton`        | `bool`                                       | whether the user will have the option to clear the selected value. When it is clicked, the `Value` will be updated to `default(TValue)`, so there must be no item in the `Data` that has such a `Value`. For example, if `TValue` is `int`, clearing the value will lead to a `0` `Value`, so if there is an Item with `0` in its `ValueField` - issues may arise with its selection. This feature can often go together with `AllowCustom`. |
| `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.                                                                                                                                                                                                                                                                                                                                                                                                            |
| `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.                                                                                                                                                                                                                                                                                              |
| `Filterable`             | `bool`                                       | whether [filtering](https://www.telerik.com/blazor-ui/documentation/components/combobox/filter) is enabled for the end user.                                                                                                                                                                                                                                                                                                                 |
| `FilterOperator`         | `StringFilterOperator` <br /> (`StartsWith`) | the method of [filtering](https://www.telerik.com/blazor-ui/documentation/components/combobox/filter) the items.                                                                                                                                                                                                                                                                                                                             |
| `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.                                                                                                                                                                                                                                                                                                                    |
| `Placeholder`            | `string`                                     | the text the user sees as a hint when no item is selected. In order for it to be shown, the `Value` parameter should be set to a default value depending on the type defined in the `ValueField` parameter. For example, `0` for an `int`, and `null` for an `int?` or `string`. You need to make sure that it does not match the value of an existing item in the data source.                                                              |
| `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.                                                                                                                                                                                                                                                                                         |
| `TValue`                 | `Type`                                       | the type of the value field from the model to which the component is bound. Required if you can't provide `Data` or `Value`. Determines the type of the reference object. The type of the values can be:<br /> - `number` (such as `int`, `double`, and so on)<br /> - `string`<br /> - `Guid`<br /> - `Enum`                                                                                                                                |
| `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).                                                                                                                                                                                                                                |
| `TextField`              | `string` <br /> (`Text`)                     | the name of the field from the model that will be shown to the user.                                                                                                                                                                                                                                                                                                                                                                         |
| `ValueField`             | `string` <br /> (`Value`)                    | the name of the field from the model that will be the underlying `value`.                                                                                                                                                                                                                                                                                                                                                                    |
| `Value` and `bind-Value` | `TValue`                                     | get/set the value of the component, can be used for binding. If you set it to a value allowed by the model class value field, the corresponding item from the data collection will be pre-selected. Use the `bind-Value` syntax for two-way binding, for example, to a variable of your own.                                                                                                                                                 |
| `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.                                                                                                                                                                                                                                                                                       |

### Styling and Appearance

The following parameters enable you to customize the [appearance](https://www.telerik.com/blazor-ui/documentation/components/combobox/appearance) of the Blazor ComboBox:

| 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). |

> tip To learn more about the appearance, anatomy, and accessibility of the ComboBox, visit the [Progress Design System Kit documentation](https://www.telerik.com/design-system/docs/components/combobox/)—an information portal offering rich component usage guidelines, descriptions of the available style variables, and globalization support details.

### Popup settings

The ComboBox exposes settings for its dropdown (popup). To configure the options, declare a  `<ComboBoxPopupSettings>` tag inside a `<ComboBoxSettings>` tag:

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

The ComboBox 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.

## ComboBox Reference and Methods

Add a reference to the component instance to use the [ComboBox's methods](https://www.telerik.com/blazor-ui/documentation/api/telerik.blazor.components.telerikcombobox-2). Note that the [ComboBox 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/combobox/methods/" height="250"></demo>

## Selected Item

By default, if no `Value` is provided, the ComboBox will appear empty, or will display the `Placeholder` defined. If a `Value` is provided and `AllowCustom` is *not* set to `true`, the `Value` should match an item in the data source (see more in the [Value Out of Range](https://www.telerik.com/blazor-ui/documentation/components/combobox/data-bind#value-out-of-range) section).

The ComboBox will not always have a selected item, however, because it can act as an input. There will be no selected item in the following cases that depend on the settings of the component that the developer can control:

* the user clears the value through the Clear button,
* the user clears the value with `Backspace` or `Del` keys,
* `AllowCustom="false"` - when a custom value is typed, the ComboBox input value will be automatically cleared on the change event (`blur` of the input or `Enter` keypress). See the table below.
* `AllowCustom="true"` - when the user starts typing a custom value.

Missing selection is most common when the initial value is `null` as data sources rarely have items with a `null` value, and/or when you want to let your users type in values that are not in your predefined set of options.

> caption If the user types text in the input, selection behaves according to the following table:

| User input matches          | AllowCustom=`true`                                            | AllowCustom=`false`                                                                                                             |
| --------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| The `TextField` of an item  | Matched item is selected. The `Value` is taken from the item. | Matched item is selected. The `Value` is taken from the item.                                                                   |
| The `ValueField` of an item | No item is selected. `Value` is updated to the custom one.    | No item is selected. `Value` is updated to `default(typeof(Value))`. The `OnChange` event does not fire for the value clearing. |
| No match                    | No item is selected. `Value` is updated to the custom one.    | No item is selected. `Value` is updated to `default(typeof(Value))`. The `OnChange` event does not fire for the value clearing. |

> 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/combobox/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>

## Next Steps

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

* [Pre-Selecting Items for the User](https://www.telerik.com/blazor-ui/documentation/components/combobox/pre-select-item)

## See Also

* [Data Binding](https://www.telerik.com/blazor-ui/documentation/components/combobox/data-bind)
* [Live Demo: ComboBox](https://demos.telerik.com/blazor-ui/combobox/overview)
* [Live Demo: ComboBox Validation](https://demos.telerik.com/blazor-ui/combobox/validation)
* [ComboBox API Reference](https://www.telerik.com/blazor-ui/documentation/api/telerik.blazor.components.telerikcombobox-2)
