You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This article explains the different ways to provide data to an AutoComplete component, the properties related to data binding and their results. The key requirements is to have a string field for the suggestions.
14
+
15
+
There are two key ways to bind data:
16
+
17
+
*[Primitive Type](#primitive-type)
18
+
*[Model](#bind-to-a-model)
19
+
20
+
There are also some [considerations](#considerations) to keep in mind.
21
+
22
+
## Primitive Types
23
+
24
+
You can data bind the AutoComplete to a simple collection of `string` data. When you have a concrete list of options for the user to choose from, their string representation is often suitable for display and you do not need special models.
25
+
26
+
To bind the AutoComplete, you need to:
27
+
28
+
1. provide an `IEnumerable<string>` to its `Data` property,
29
+
1. point the `Value` parameter to a `string` field.
30
+
31
+
>caption Data binding an AutoComplete to a simple data source
string[] ArraySuggestions = new string[] { "one", "two", "three" };
51
+
}
52
+
````
53
+
54
+
## Bind to a Model
55
+
56
+
You can bind the AutoComplete to a model in your application. This is useful when you have the data in some form already and you don't need to prepare a separate collection of suggestions.
57
+
58
+
To bind the AutoComplete to a model:
59
+
60
+
1. populate its `Data` property with the collection of items you want in the dropdown
61
+
1. set the `TextField` to point to the corresponding name of the model that contains the string data for the suggestions
62
+
1. point the `Value` parameter to a `string` field in the view-model.
List<SuggestionsModel> Suggestions { get; set; } = new List<SuggestionsModel>
118
+
{
119
+
new SuggestionsModel { Suggestion = "first", SomeOtherField = 1 },
120
+
new SuggestionsModel { Suggestion = "second", SomeOtherField = 2 },
121
+
new SuggestionsModel { Suggestion = "third", SomeOtherField = 3 }
122
+
};
123
+
124
+
public class SuggestionsModel
125
+
{
126
+
public string Suggestion { get; set; }//the auto complete needs only the string field
127
+
public int SomeOtherField { get; set; }
128
+
}
129
+
}
130
+
````
131
+
132
+
### Missing Data
133
+
134
+
The AutoComplete is, essentially, a textbox. This means that its `Value` is always a string and it is up to you to bind and/or use it. The `Data` parameter, however, is required for the functionality of the component, and it must never be `null`. If there are no suggestions that you wish to provide to the user, consider using a regular TextBox, or creating an empty collection.
135
+
136
+
>caption Minimal AutoComplete configuration for it to run
137
+
138
+
````CSHTML
139
+
@* If you cannot provide suggestions list, use an empty collection and the component will show "No Data" to the user in the suggestions list *@
140
+
141
+
<TelerikAutoComplete Data="@Suggestions" />
142
+
143
+
@code{
144
+
List<string> Suggestions { get; set; } = new List<string>();
Copy file name to clipboardExpand all lines: components/autocomplete/overview.md
+29-73Lines changed: 29 additions & 73 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,105 +10,61 @@ position: 0
10
10
11
11
# AutoComplete Overview
12
12
13
-
The ComboBox component 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]({%slug components/combobox/custom-value%}) and to [filter]({%slug components/combobox/filter%}) the available items. You can control the [data]({%slug components/dropdownlist/databind%}), sizes, and various appearance options like class and [templates]({%slug components/combobox/templates%}).
13
+
The AutoComplete component is a textbox that offers the users hints as they type. These suggestions can be [filtered]({%slug 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]({%slug autocomplete-databind%}), various appearance settings like [dimensions]({%slug common-features/dimensions%}) and [templates]({%slug autocomplete-templates%}).
14
14
15
-
To use a Telerik ComboBox for Blazor
15
+
To use a Telerik AutoComplete for Blazor
16
16
17
-
1. add the `TelerikComboBox` tag
17
+
1. add the `TelerikAutoComplete` tag
18
18
1. populate its `Data` property with the collection of items you want in the dropdown
19
-
1. set the `TextField` and `ValueField` properties to point to the corresponding names of the model
20
-
1. (optional) set the `Value` property to the initial value of the model.
21
-
1. (optional) enable features like filtering and clear button
19
+
1. (optional) enable features like [filtering]({%slug autocomplete-filter%}) and clear button
22
20
23
-
>caption Combobox [data binding](data-bind), two-way value binding and main features
21
+
>caption AutoComplete two-way value binding, main features and simple [data binding](data-bind)
>caption The result from the code snippet above, as the user types a custom value
49
40
50
-
41
+
51
42
52
43
>caption Component namespace and reference
53
44
54
-
The ComboBox is a generic component and its type is determined by the type of the model you pass to it, and the type of its value field. You can find examples in the [Data Bind - Considerations]({%slug components/combobox/databind%}#considerations) article.
45
+
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]({%slug autocomplete-databind%}#considerations) article.
55
46
56
-
>caption The ComboBox provides the following features:
47
+
>caption The AutoComplete provides the following features:
57
48
58
-
*`AllowCustom` - whether the user can enter [custom values]({%slug components/combobox/custom-value%}). If enabled, the `ValueField` must be a `string`.
59
49
*`Class` - the CSS class that will be rendered on the main wrapping element of the combobox.
60
-
*`ClearButton` - 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`.
50
+
*`ClearButton` - 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`.
61
51
*`Data` - allows you to provide the data source. Required.
62
52
*`Enabled` - whether the component is enabled.
63
-
*`Filterable` - whether [filtering]({%slug components/combobox/filter%}) is enabled for the end user.
64
-
*`Placeholder` - the text the user sees as a hint when no item is selected (the `Value` is `null` or an empty string).
53
+
*`Filterable` - whether [filtering]({%slug autocomplete-filter%}) is enabled for the end user (suggestions will get narrowed down as they type).
54
+
*`Placeholder` - the text the user sees as a hint when there is no text in the input.
65
55
*`PopupHeight` - the height of the expanded dropdown list element.
56
+
*`PopupWidth` - the width of the expanded dropdown list element.
66
57
*`TItem` - 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.
67
-
*`TValue` - 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.
68
-
*`TextField` - the name of the field from the model that will be shown to the user. Defaults to `Text`.
69
-
*`ValueField` - the name of the field from the model that will be the underlying `value`. Defaults to `Value`.
70
-
*`Value` and `bind-Value`- 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.
71
-
72
-
The `Value` and `ValueField` can be of types:
73
-
74
-
*`number` (such as `int`, `double` and so on)
75
-
*`string`
76
-
*`Guid`
77
-
*`Enum`
78
-
*`Width` - the width of the dropdown and the main element.
79
-
* Templates - they allow you to control the rendering of items in the component. See the [Templates]({%slug components/combobox/templates%}) article for more details.
58
+
*`TextField` - the name of the field from the model that will be shown as hints to the user. Defaults to `Text`. Not required when binding to a simple list of strings.
59
+
*`Value` and `bind-Value`- 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`.
60
+
*`Width` - the width of the main element.
61
+
* Templates - they allow you to control the rendering of items in the component. See the [Templates]({%slug autocomplete-templates%}) article for more details.
80
62
* Validation - see the [Input Validation]({%slug common-features/input-validation%}) article for more details.
81
63
82
64
83
-
## Selected Item
84
-
85
-
By default, if no `Value` is provided, the ComboBox will appear empty, or will display the `Placeholder` defined. If a `Value` is provided, the first item from the data source whose ValueField matches will be selected.
86
-
87
-
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:
88
-
89
-
* the user clears the value through the Clear button,
90
-
* the user clears the value with `Backspace` or `Del` keys,
91
-
*`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.
92
-
*`AllowCustom="true"` - when the user starts typing a custom value.
93
-
94
-
95
-
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.
96
-
97
-
>caption If the user types text in the input, selection behaves according to the following table:
98
-
99
-
100
-
| 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. |
103
-
| 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. |
104
-
| 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. |
0 commit comments