Skip to content

Commit cd2c5b3

Browse files
svdimitrjivanova
svdimitr
authored and
jivanova
committed
docs(mc-combo): overview article
1 parent 906b9a3 commit cd2c5b3

File tree

1 file changed

+182
-0
lines changed

1 file changed

+182
-0
lines changed

‎components/multicolumncombobox/overview.md‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
---
2+
title: Overview
3+
page_title: MultiColumnComboBox Overview
4+
description: Discover the Blazor MultiColumnComboBox and explore the examples.
5+
slug: multicolumncombobox-overview
6+
tags: telerik,blazor,multicolumncombobox,combo,columns,overview
7+
published: True
8+
position: 0
9+
---
10+
11+
# Blazor MultiColumnComboBox Overview
12+
13+
The <a href="https://www.telerik.com/blazor-ui/multicolumn-combobox" target="_blank">Blazor MultiColumnComboBox</a> allows the user to choose an option from a [predefined set of choices]({%slug multicolumncombobox-data-binding%}) in a dropdown grid structure. You can also allow them to enter [custom values]({%slug multicolumncombobox-custom-value%}), [filter]({%slug multicolumncombobox-filter%}) the available items, and [group]({%slug multicolumncombobox-group%}) the listed items in common categories.
14+
15+
## Creating MultiColumnComboBox
16+
17+
1. Use the `TelerikMultiColumnComboBox` tag to add the component to your razor page.
18+
1. Populate the `Data` property with the collection of items that you want to appear in the dropdown.
19+
1. Set the `TextField` and `ValueField` properties to point to the corresponding names of the model
20+
1. [Bind the value of the component]({%slug get-started-value-vs-data-binding %}#value-binding) to a variable of the same type as the type defined in the `ValueField` parameter.
21+
1. Add `MultiColumnComboBoxColumn` instances under the `MultiColumnComboBoxColumns` tag. Each column, the `Field` must point to a property in the bound model property. Use `nameof()` or the plain field name.
22+
23+
>caption MultiColumnComboBox data binding with two-way value binding
24+
25+
````CSHTML
26+
Selected value: @BoundValue
27+
<br />
28+
29+
<TelerikMultiColumnComboBox Data="@MultiComboData"
30+
@bind-Value="@BoundValue"
31+
ValueField="@nameof(SampleData.Id)"
32+
TextField="@nameof(SampleData.Name)">
33+
<MultiColumnComboBoxColumns>
34+
<MultiColumnComboBoxColumn Field="@nameof(SampleData.Id)" Title="The id" ></MultiColumnComboBoxColumn>
35+
<MultiColumnComboBoxColumn Field="@nameof(SampleData.Name)" Title="The name"></MultiColumnComboBoxColumn>
36+
</MultiColumnComboBoxColumns>
37+
</TelerikMultiColumnComboBox>
38+
39+
@code {
40+
public int BoundValue { get; set; }
41+
42+
public List<SampleData> MultiComboData { get; set; } = Enumerable.Range(0, 30).Select(x => new SampleData()
43+
{
44+
Id = x,
45+
Name = "Name " + x
46+
}).ToList();
47+
48+
public class SampleData
49+
{
50+
public int Id { get; set; }
51+
public string Name { get; set; }
52+
}
53+
}
54+
````
55+
56+
## Component Reference
57+
58+
The MultiColumnComboBox 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 multicolumncombobox-data-binding%}#considerations) article.
59+
60+
## Data Binding
61+
62+
The Blazor MultiColumnComboBox @[template](/_contentTemplates/dropdowns/features.md#data-binding) [Read more about the Blazor MultiColumnComboBox data binding...]({% slug multicolumncombobox-data-binding %}).
63+
64+
## Columns
65+
66+
The Blazor MultiColumnComboBox allows you to define one or more columns in the dropdown. [Read more about the Blazor MultiColumnComboBox columns...]({%slug multicolumncombobox-column-overview%})
67+
68+
## Filtering
69+
70+
The Blazor MultiColumnComboBox @[template](/_contentTemplates/dropdowns/features.md#filtering) [Read more about the Blazor ComboBox filter...]({% slug cmulticolumncombobox-filter %}).
71+
72+
## Grouping
73+
74+
The Blazor MultiColumnComboBox @[template](/_contentTemplates/dropdowns/features.md#grouping) [Read more about the Blazor MultiColumnComboBox grouping...]({% slug multicolumncombobox-group %}).
75+
76+
## Templates
77+
78+
@[template](/_contentTemplates/dropdowns/features.md#templates) [Read more about the Blazor MultiColumnComboBox templates...]({% slug multicolumncombobox-templates %}).
79+
80+
## Validation
81+
82+
@[template](/_contentTemplates/dropdowns/features.md#validation)
83+
84+
## Virtualization
85+
86+
@[template](/_contentTemplates/dropdowns/features.md#virtualization) [Read more about the Blazor MultiColumnComboBox virtualization...]({% slug multicolumncombobox-virtualization %})
87+
88+
89+
## Parameters
90+
91+
>caption The ComboBox provides various parameters that allow you to configure the component:
92+
93+
<style>
94+
article style + table {
95+
table-layout: auto;
96+
word-break: normal;
97+
}
98+
</style>
99+
| Parameter | Type | Description
100+
| ----------- | ----------- | -----------|
101+
| `AllowCustom` | `bool` | whether the user can enter [custom values]({%slug components/combobox/custom-value%}). If enabled, the `ValueField` must be a `string`.
102+
| `ClearButton` | `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`.
103+
| `Data` | `IEnumerable<TItem>` | allows you to provide the data source. Required.
104+
| `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.
105+
| `Enabled` | `bool` | whether the component is enabled.
106+
|`Filterable` | `bool` | whether [filtering]({%slug components/combobox/filter%}) is enabled for the end user.
107+
| `FilterOperator` | `StringFilterOperator` <br /> (`StartsWith`) | the method of [filtering]({%slug components/combobox/filter%}) the items.
108+
| `Id` | `string` | renders as the `id` attribute on the `<input />` element, so you can attach a `<label for="">` to the input.
109+
| `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.
110+
| `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.
111+
| `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`|
112+
| `TextField` | `string` <br /> (`Text`)| the name of the field from the model that will be shown to the user.
113+
| `ValueField` | `string` <br /> (`Value`) | the name of the field from the model that will be the underlying `value`.
114+
| `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.
115+
| `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.
116+
117+
### Styling and Appearance
118+
119+
The following parameters enable you to customize the appearance of the Blazor ComboBox:
120+
121+
@[template](/_contentTemplates/dropdowns/features.md#styling)
122+
123+
You can find more options for customizing the ComboBox styling in the [Appearance article]({%slug combobox-appearance%}).
124+
125+
126+
### Popup settings
127+
128+
The popup of the component can be additionally customized via nested tags:
129+
130+
````
131+
<div class="skip-repl"></div>
132+
<TelerikComboBox>
133+
<ComboBoxSettings>
134+
<ComboBoxPopupSettings Height="..." />
135+
</ComboBoxSettings>
136+
</TelerikComboBox>
137+
````
138+
139+
The ComboBox provides the following popup settings:
140+
141+
@[template](/_contentTemplates/dropdowns/features.md#popup-settings)
142+
143+
144+
## Selected Item
145+
146+
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]({%slug components/combobox/databind%}#value-out-of-range) section).
147+
148+
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:
149+
150+
* the user clears the value through the Clear button,
151+
* the user clears the value with `Backspace` or `Del` keys,
152+
* `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.
153+
* `AllowCustom="true"` - when the user starts typing a custom value.
154+
155+
156+
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.
157+
158+
>caption If the user types text in the input, selection behaves according to the following table:
159+
160+
161+
| User input matches | AllowCustom=`true` | AllowCustom=`false` |
162+
|----------------------------|----------------------|------------------------------------------|
163+
| 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. |
164+
| 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. |
165+
| 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. |
166+
167+
168+
@[template](/_contentTemplates/common/get-model-from-dropdowns.md#get-model-from-dropdowns)
169+
170+
## Next Steps
171+
172+
* [Binding the ComboBox to Data]({%slug components/combobox/databind%})
173+
174+
* [Pre-Selecting Items for the User]({% slug combobox-pre-select-item %})
175+
176+
## See Also
177+
178+
* [Data Binding]({%slug components/combobox/databind%})
179+
* [Live Demo: ComboBox](https://demos.telerik.com/blazor-ui/combobox/overview)
180+
* [Live Demo: ComboBox Validation](https://demos.telerik.com/blazor-ui/combobox/validation)
181+
* [API Reference](https://docs.telerik.com/blazor-ui/api/Telerik.Blazor.Components.TelerikComboBox-2)
182+

0 commit comments

Comments
 (0)