Skip to content

Commit d94b0d3

Browse files
dimodidimodi
authored
kb(Dropdowns): Add KB for disabled select items (#3156)
* kb(Dropdowns): Add KB for disabled select items * polishing * Update knowledge-base/dropdown-disabled-items.md * Update knowledge-base/dropdown-disabled-items.md * Address PR comments
1 parent dccf38b commit d94b0d3

File tree

1 file changed

+298
-0
lines changed

1 file changed

+298
-0
lines changed

‎knowledge-base/dropdown-disabled-items.md

Lines changed: 298 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,298 @@
1+
---
2+
title: Disable Dropdown Item for Selection
3+
description: Learn how to use disabled items in a ComboBox or DropDownList that are visible, but cannot be selected by the user.
4+
type: how-to
5+
page_title: How to Disable ComboBox or DropDownList Item for Selection
6+
slug: dropdown-kb-disabled-items
7+
tags: telerik, blazor, combobox, dropdownlist, multiselect, selection
8+
ticketid: 1474264, 1593235, 1683944, 1695111
9+
res_type: kb
10+
---
11+
12+
## Environment
13+
14+
<table>
15+
<tbody>
16+
<tr>
17+
<td>Product</td>
18+
<td>
19+
ComboBox for Blazor, <br />
20+
DropDownList for Blazor, <br />
21+
MultiSelect for Blazor
22+
</td>
23+
</tr>
24+
</tbody>
25+
</table>
26+
27+
## Description
28+
29+
This KB article shows how to use disabled non-selectable items in the Telerik ComboBox, DropDownList, and MultiSelect components for Blazor.
30+
31+
The page also answers the following questions:
32+
33+
* How to disable certain items in the ComboBox dropdown (popup)?
34+
* How to denote if a DropDownList or MultiSelect item is selectable or disabled?
35+
* How to flag data items in the Blazor ComboBox that are disabled and no longer available and selectable?
36+
37+
## Solution
38+
39+
The following algorithm applies to the Telerik Blazor ComboBox, DropDownList, and MultiSelect. Review the examples below for some minor implementation differences.
40+
41+
1. Use the component's `OnItemRender` event to apply a `k-disabled` CSS class to non-selectable items. This prevents selection disabled items with a click or tap.
42+
1. Use the component's `ValueChanged` event to track the user selection and override it. This applies especially to ComboBox and DropDownList keyboard navigation, where you should select the next or previous enabled item in the list.
43+
44+
### ComboBox
45+
46+
Reset the ComboBox value to default and then [`Rebind()`](slug:common-features-data-binding-overview#refresh-data) the component after overriding the user selection.
47+
48+
>caption Use disabled unselectable items in a ComboBox
49+
50+
````RAZOR
51+
<TelerikComboBox @ref="@ComboBoxRef"
52+
Data="@Products"
53+
Value="@ComboBoxValue"
54+
ValueChanged="@( (int? newValue) => ComboBoxValueChanged(newValue) )"
55+
TextField="@nameof(Product.Name)"
56+
ValueField="@nameof(Product.Id)"
57+
Placeholder="Select Product..."
58+
OnItemRender="@OnComboBoxItemRender"
59+
Width="200px">
60+
</TelerikComboBox>
61+
62+
@code {
63+
private TelerikComboBox<Product, int?>? ComboBoxRef { get; set; }
64+
65+
private List<Product> Products { get; set; } = new();
66+
67+
private int? ComboBoxValue { get; set; }
68+
69+
private void OnComboBoxItemRender(ComboBoxItemRenderEventArgs<Product> args)
70+
{
71+
if (!args.Item.Enabled)
72+
{
73+
args.Class = "k-disabled";
74+
}
75+
}
76+
77+
private async Task ComboBoxValueChanged(int? newValue)
78+
{
79+
var newProduct = Products.FirstOrDefault(x => x.Id == newValue);
80+
81+
// Select only enabled items or null.
82+
if (newProduct?.Enabled == true || !newValue.HasValue)
83+
{
84+
ComboBoxValue = newValue;
85+
}
86+
else
87+
{
88+
// Skip disabled items during keyboard navigation.
89+
// For simplicity, this logic does not handle adjacent disabled items.
90+
int oldProductIndex = Products.FindIndex(x => x.Id == ComboBoxValue);
91+
int newProductIndex = Products.FindIndex(x => x.Id == newValue);
92+
93+
ComboBoxValue = default;
94+
await Task.Delay(1);
95+
96+
if (newProductIndex > oldProductIndex && Products.Count > newProductIndex + 1)
97+
{
98+
ComboBoxValue = Products[++newProductIndex].Id;
99+
}
100+
else if (newProductIndex > 0)
101+
{
102+
ComboBoxValue = Products[--newProductIndex].Id;
103+
}
104+
else
105+
{
106+
ComboBoxValue = default;
107+
}
108+
109+
ComboBoxRef?.Rebind();
110+
}
111+
}
112+
113+
protected override void OnInitialized()
114+
{
115+
for (int i = 1; i <= 10; i++)
116+
{
117+
var enabled = i % 3 != 0;
118+
119+
Products.Add(new Product()
120+
{
121+
Id = i,
122+
Name = $"{(enabled ? "" : "Disabled ")}Product {i}",
123+
Enabled = enabled
124+
});
125+
}
126+
127+
base.OnInitialized();
128+
}
129+
130+
public class Product
131+
{
132+
public int? Id { get; set; }
133+
public string Name { get; set; } = string.Empty;
134+
public bool Enabled { get; set; } = true;
135+
}
136+
}
137+
````
138+
139+
### DropDownList
140+
141+
Unlike the ComboBox, the DropDownList does not need value resetting and `Rebind()` when overriding the user selection.
142+
143+
>caption Use disabled unselectable items in a DropDownList
144+
145+
````RAZOR
146+
<TelerikDropDownList Data="@Products"
147+
Value="@DropDownListValue"
148+
ValueChanged="@( (int? newValue) => DropDownListValueChanged(newValue) )"
149+
TextField="@nameof(Product.Name)"
150+
ValueField="@nameof(Product.Id)"
151+
DefaultText="Select Product..."
152+
OnItemRender="@OnDropDownListItemRender"
153+
Width="200px">
154+
</TelerikDropDownList>
155+
156+
@code {
157+
private List<Product> Products { get; set; } = new();
158+
159+
private int? DropDownListValue { get; set; }
160+
161+
private void OnDropDownListItemRender(DropDownListItemRenderEventArgs<Product> args)
162+
{
163+
// args.Item is null for the DefaultText item.
164+
if (args.Item != null && !args.Item.Enabled)
165+
{
166+
args.Class = "k-disabled";
167+
}
168+
}
169+
170+
private void DropDownListValueChanged(int? newValue)
171+
{
172+
var newProduct = Products.FirstOrDefault(x => x.Id == newValue);
173+
174+
// Select only enabled items or DefaultText.
175+
if (newProduct?.Enabled == true || !newValue.HasValue)
176+
{
177+
DropDownListValue = newValue;
178+
}
179+
else
180+
{
181+
// Skip disabled items during keyboard navigation.
182+
// For simplicity, this logic does not handle adjacent disabled items.
183+
int oldProductIndex = Products.FindIndex(x => x.Id == DropDownListValue);
184+
int newProductIndex = Products.FindIndex(x => x.Id == newValue);
185+
186+
if (newProductIndex > oldProductIndex && Products.Count > newProductIndex + 1)
187+
{
188+
DropDownListValue = Products[++newProductIndex].Id;
189+
}
190+
else if (newProductIndex > 0)
191+
{
192+
DropDownListValue = Products[--newProductIndex].Id;
193+
}
194+
else
195+
{
196+
DropDownListValue = default;
197+
}
198+
}
199+
}
200+
201+
protected override void OnInitialized()
202+
{
203+
for (int i = 1; i <= 10; i++)
204+
{
205+
var enabled = i % 3 != 0;
206+
207+
Products.Add(new Product()
208+
{
209+
Id = i,
210+
Name = $"{(enabled ? "" : "Disabled ")}Product {i}",
211+
Enabled = enabled
212+
});
213+
}
214+
215+
base.OnInitialized();
216+
}
217+
218+
public class Product
219+
{
220+
public int Id { get; set; }
221+
public string Name { get; set; } = string.Empty;
222+
public bool Enabled { get; set; } = true;
223+
}
224+
}
225+
````
226+
227+
### MultiSelect
228+
229+
The MultiSelect implementation is simpler, because there is no need to deliberately skip items during keyboard navigation with the arrow keys.
230+
231+
>caption Use disabled unselectable items in a MultiSelect
232+
233+
````RAZOR
234+
<TelerikMultiSelect Data="@Products"
235+
Value="@MultiSelectValues"
236+
ValueChanged="@( (List<int> newValues) => MultiSelectValueChanged(newValues) )"
237+
TextField="@nameof(Product.Name)"
238+
ValueField="@nameof(Product.Id)"
239+
AutoClose="false"
240+
Placeholder="Select Products..."
241+
ShowArrowButton="true"
242+
OnItemRender="@OnMultiSelectItemRender"
243+
Width="600px" />
244+
245+
@code {
246+
private List<Product> Products { get; set; } = new();
247+
private List<int> EnabledProductIds { get; set; } = new();
248+
249+
private int? SelectedValue { get; set; }
250+
251+
private List<int> MultiSelectValues { get; set; } = new();
252+
253+
private void OnMultiSelectItemRender(MultiSelectItemRenderEventArgs<Product> args)
254+
{
255+
if (!args.Item.Enabled)
256+
{
257+
args.Class = "k-disabled";
258+
}
259+
}
260+
261+
private void MultiSelectValueChanged(List<int> newValues)
262+
{
263+
MultiSelectValues = newValues.Where(x => EnabledProductIds.Contains(x)).ToList();
264+
}
265+
266+
protected override void OnInitialized()
267+
{
268+
for (int i = 1; i <= 10; i++)
269+
{
270+
var enabled = i % 3 != 0;
271+
272+
Products.Add(new Product()
273+
{
274+
Id = i,
275+
Name = $"{(enabled ? "" : "Disabled ")}Product {i}",
276+
Enabled = enabled
277+
});
278+
}
279+
280+
EnabledProductIds = Products.Where(x => x.Enabled).Select(x => x.Id).ToList();
281+
282+
base.OnInitialized();
283+
}
284+
285+
public class Product
286+
{
287+
public int Id { get; set; }
288+
public string Name { get; set; } = string.Empty;
289+
public bool Enabled { get; set; } = true;
290+
}
291+
}
292+
````
293+
294+
## See Also
295+
296+
* [ComboBox Events](slug:components/combobox/events)
297+
* [DropDownList Events](slug:components/dropdownlist/events)
298+
* [MultiSelect Events](slug:multiselect-events)

0 commit comments

Comments
 (0)