syncfusion/wpf-ui-components-skills / skills/syncfusion-wpf-checkedlistbox
syncfusion-wpf-checkedlistbox
VerifiedImplements the Syncfusion WPF CheckedListBox (CheckListBox) control for multi-select lists with checkboxes. Use this when adding checklist controls, checkbox-enabled item lists, or SelectAll functionality in WPF applications. Covers data binding, appearance customization, grouping/sorting, item selection handling, and virtualization.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 12.0 KB |
| references/appearance-customization-examples.md | markdown | 3.1 KB |
| references/appearance-customization.md | markdown | 886 B |
| references/checking-and-selection-advanced.md | markdown | 2.2 KB |
| references/checking-and-selection.md | markdown | 7.3 KB |
| references/data-binding-examples.md | markdown | 2.0 KB |
| references/data-binding.md | markdown | 10.3 KB |
| references/getting-started-extras.md | markdown | 2.1 KB |
| references/getting-started.md | markdown | 10.4 KB |
| references/grouping-and-sorting-examples.md | markdown | 1.5 KB |
| references/grouping-and-sorting.md | markdown | 11.7 KB |
| references/layout-features.md | markdown | 3.0 KB |
| references/virtualization.md | markdown | 13.5 KB |
references/checking-and-selection.md
View on GitHub# Item Checking and Selection (summary)
This file covers the essential patterns for checking and selecting items in the CheckListBox. Extended examples and advanced scenarios have been moved to a companion file to reduce length.
Core recommendations:
- For reliability and virtualization compatibility, use the `SelectedItems` collection to programmatically check/uncheck items.
- Use `ItemContainerStyle` binding `IsSelected` ↔ model boolean for small datasets or when virtualization is disabled.
- Control click behavior with `IsCheckOnFirstClick` and enable `IsSelectAllEnabled` to show a global select-all checkbox.
Common APIs:
- `SelectedItems` — all currently checked items
- `SelectedItem` — focused item
- `ItemChecked` event — fires on check state changes
For advanced patterns, pre-checking, validation, and extended examples see: [checking-and-selection-advanced.md](checking-and-selection-advanced.md)
```csharp
checkListBox.ItemChecked += (sender, e) =>
{
var item = e.Item;
MessageBox.Show($"Item {item} is now {(e.IsChecked ? "checked" : "unchecked")}");
};
```
**Use cases:**
- Update summary counts
- Validate selection rules
- Trigger dependent actions
- Log user selections
- Update related UI elements
### SelectionChanged Event
Fires when the focused item changes (not necessarily when checked state changes).
**Event signature:**
```csharp
public event SelectionChangedEventHandler SelectionChanged;
```
**SelectionChangedEventArgs properties:**
- `AddedItems` - Items added to selection
- `RemovedItems` - Items removed from selection
**XAML:**
```xml
<syncfusion:CheckListBox SelectionChanged="CheckListBox_SelectionChanged" />
```
**Event handler:**
```csharp
private void CheckListBox_SelectionChanged(object sender, SelectionChangedEventArgs e)
{
// Items added to selection
foreach (var item in e.AddedItems)
{
Console.WriteLine($"Added: {item}");
}
// Items removed from selection
foreach (var item in e.RemovedItems)
{
Console.WriteLine($"Removed: {item}");
}
}
```
**⚠️ Important Distinction:**
- `ItemChecked` = Checkbox state changed (checked/unchecked)
- `SelectionChanged` = Focused item changed (focus moved)
## Getting Checked Items
### SelectedItems Property
Returns a collection of all currently checked items.
**Basic usage:**
```csharp
// Get all checked items
var checkedItems = checkListBox.SelectedItems;
// Count checked items
int count = checkedItems.Count;
// Iterate through checked items
foreach (var item in checkedItems)
{
var checkListItem = item as CheckListBoxItem;
Console.WriteLine(checkListItem.Content);
}
```
**With data binding:**
```csharp
// Assuming ItemsSource is ObservableCollection<Vegetable>
foreach (var item in checkListBox.SelectedItems)
{
var vegetable = item as Vegetable;
Console.WriteLine($"{vegetable.Name} - {vegetable.Category}");
}
```
**Display checked items in UI:**
```csharp
private void ShowCheckedItems_Click(object sender, RoutedEventArgs e)
{
var sb = new StringBuilder();
sb.AppendLine($"Total Checked: {checkListBox.SelectedItems.Count}");
sb.AppendLine();
foreach (var item in checkListBox.SelectedItems)
{
var vegetable = item as Vegetable;
sb.AppendLine($"✓ {vegetable.Name} ({vegetable.Category})");
}
MessageBox.Show(sb.ToString(), "Checked Items");
}
```
### SelectedItem Property
Returns the currently focused item (whether checked or not).
```csharp
// Get focused item
var currentItem = checkListBox.SelectedItem;
if (currentItem != null)
{
var vegetable = currentItem as Vegetable;
MessageBox.Show($"Currently focused: {vegetable.Name}");
}
```
**Key difference:**
- `SelectedItems` (plural) = All checked items
- `SelectedItem` (singular) = Currently focused item
## Advanced Scenarios
### Programmatic Check/Uncheck All
**Check all items:**
```csharp
public void CheckAll()
{
foreach (var item in checkListBox.Items)
{
if (!checkListBox.SelectedItems.Contains(item))
{
checkListBox.SelectedItems.Add(item);
}
}
}
```
**Uncheck all items:**
```csharp
public void UncheckAll()
{
checkListBox.SelectedItems.Clear();
}
```
**Toggle all items:**
```csharp
public void ToggleAll()
{
if (checkListBox.SelectedItems.Count == checkListBox.Items.Count)
{
// All checked, so uncheck all
checkListBox.SelectedItems.Clear();
}
else
{
// Some unchecked, so check all
CheckAll();
}
}
```
### Conditional Selection
**Check items based on criteria:**
```csharp
public void CheckItemsAbovePrice(int minPrice)
{
foreach (Vegetable vegetable in checkListBox.Items)
{
if (vegetable.Price > minPrice)
{
if (!checkListBox.SelectedItems.Contains(vegetable))
{
checkListBox.SelectedItems.Add(vegetable);
}
}
}
}
```
**Check items by category:**
```csharp
public void CheckByCategory(string category)
{
foreach (Vegetable vegetable in checkListBox.Items)
{
if (vegetable.Category == category)
{
checkListBox.SelectedItems.Add(vegetable);
}
}
}
```
### Validation Rules
**Limit maximum selections:**
```csharp
private void CheckListBox_ItemChecked(object sender, ItemCheckedEventArgs e)
{
const int maxSelections = 3;
if (e.IsChecked && checkListBox.SelectedItems.Count > maxSelections)
{
// Remove the item that was just checked
checkListBox.SelectedItems.Remove(e.Item);
MessageBox.Show($"Maximum {maxSelections} items can be selected.",
"Selection Limit", MessageBoxButton.OK, MessageBoxImage.Warning);
}
}
```
**Require minimum selections:**
```csharp
private void SaveButton_Click(object sender, RoutedEventArgs e)
{
const int minSelections = 2;
if (checkListBox.SelectedItems.Count < minSelections)
{
MessageBox.Show($"Please select at least {minSelections} items.",
"Validation", MessageBoxButton.OK, MessageBoxImage.Warning);
return;
}
// Proceed with save
SaveSelections();
}
```
### Export Checked Items
```csharp
public List<T> GetCheckedItems<T>()
{
return checkListBox.SelectedItems.Cast<T>().ToList();
}
// Usage
var checkedVegetables = GetCheckedItems<Vegetable>();
```
## Troubleshooting
**Issue: SelectedItems not updating**
- Ensure items are added/removed from collection correctly
- Check if virtualization is enabled with IsChecked binding
- Verify binding mode is TwoWay if using ItemContainerStyle
**Issue: ItemChecked event not firing**
- Verify event handler is attached
- Check if IsCheckOnFirstClick conflicts with expected behavior
- Ensure items are being checked (not just focused)
**Issue: SelectAll not appearing**
- Set `IsSelectAllEnabled="True"`
- Check if control has enough space
- Verify template hasn't been customized to hide it
**Issue: Can't check items programmatically**
- Items must exist in Items collection before adding to SelectedItems
- Use correct item reference (object from ItemsSource, not new instance)
- Check for binding errors in Output window
## Next Steps
- **Organize Items:** [grouping-and-sorting.md](grouping-and-sorting.md)
- **Customize Look:** [appearance-customization.md](appearance-customization.md)
- **Optimize Performance:** [virtualization.md](virtualization.md)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |