# WinUI controls and desktop patterns

## Contents

1. Selection method
2. Navigation and window shell
3. Collections and structured data
4. Input controls and forms
5. Commands and menus
6. Feedback and transient surfaces
7. Common page patterns
8. Control review checklist
9. Official sources

## 1. Selection method

Choose controls by semantics and built-in behavior:

1. Identify whether the user is navigating, selecting, invoking, editing, comparing, or inspecting.
2. Prefer the control that already implements the expected keyboard, focus, selection, automation, and theme behavior.
3. Check availability against the exact Windows App SDK or Toolkit version.
4. Customize styles before templates; replace the control only if its interaction model is wrong.
5. Record accessibility, localization, performance, maintenance, and licensing costs for third-party controls.

Do not choose a control from a screenshot alone. Two controls can look similar while exposing different semantics to keyboard and assistive technology.

## 2. Navigation and window shell

| Intent | Use | Avoid |
|---|---|---|
| Top-level app destinations | `NavigationView` | custom sidebar without Windows navigation behavior |
| Small set of static peer views | `SelectorBar` or a simple selector appropriate to content | document-style tabs for unrelated destinations |
| Open documents or closeable workspaces | `TabView` | `NavigationView` items masquerading as documents |
| Hierarchical location path | `BreadcrumbBar` | concatenated text and separators |
| Hierarchical data | `TreeView` | recursively nested `ListView` controls |
| List and selected item | list/details pattern | forcing every detail into a modal |

Keep top-level navigation shallow, stable, and labeled. Select top or left `NavigationView` by content breadth, localization, growth, window width, and command density—not a universal item-count rule. Let `PaneDisplayMode="Auto"` and control thresholds handle common adaptive behavior unless the experience requires deliberate states.

Use `Frame` only when page navigation and a back stack match the experience. Preserve selection, filter, scroll, and unsaved state when navigating back. Do not show a back button if there is nowhere meaningful to go.

For Windows App SDK 1.7 or later, prefer the WinUI `TitleBar` control for a customized title bar and coordinate it with `NavigationView`. On earlier versions, use the supported `Window.ExtendsContentIntoTitleBar` and `Window.SetTitleBar` path. Preserve caption buttons, drag regions, system menu access, active/inactive appearance, and resize behavior.

Use additional windows for genuinely parallel or detachable work, not as a replacement for information hierarchy. Define owner, activation, placement, close behavior, and state synchronization.

## 3. Collections and structured data

| Need | Preferred option | Notes |
|---|---|---|
| Text-heavy selectable collection | `ListView` | mature selection, grouping, reorder, and virtualization behavior |
| Uniform visual tiles | `GridView` | use a virtualizing items panel |
| Flexible list/grid/custom layouts | `ItemsView` | modern composition with layout switching and built-in selection/accessibility |
| Low-level custom virtualized layout | `ItemsRepeater` | selection, invocation, focus, and automation may need extra engineering |
| Hierarchy | `TreeView` | supports single and multiple selection |
| Simple read-only rows and columns | templated `ListView`/`ItemsView` | provide headers and accessible relationships |
| Full spreadsheet-like editing | verified maintained table component | validate keyboard, UI Automation, virtualization, sorting, resize, and editing |

Do not decide `ListView` versus a data table from a fixed threshold such as 20 rows. Base the choice on column relationships, comparison, sorting, editing, selection, virtualization, and keyboard navigation.

The Windows Community Toolkit `DataGrid` documentation is archived; it is not a current WCT 8+ WinUI 3 control. For new work, evaluate currently maintained options such as Toolkit Labs `DataTable` or the community `WinUI.TableView`, and explicitly verify their maturity and requirements. Do not silently introduce one.

Keep virtualization enabled for large or unbounded collections. Never replace a virtualizing panel with a generic panel without measuring the result. Provide loading, empty, filtered-empty, partial-data, stale, and load-failure states.

For selection, support Windows conventions: click/tap for a single item, Ctrl for independent selection, Shift for ranges, Space for focused selection where the control supports it, and visible selection independent from keyboard focus.

## 4. Input controls and forms

| Intent | Use | Important distinction |
|---|---|---|
| Short or multiline plain text | `TextBox` | use `AcceptsReturn` and suitable wrapping for multiline |
| Rich formatted editing | `RichEditBox` | do not use for plain multiline text |
| Numeric value | `NumberBox` | still validate range and domain constraints |
| Date | `DatePicker` or `CalendarDatePicker` | choose persistent picker versus compact calendar entry |
| Time | `TimePicker` | respect locale formatting |
| Immediate on/off setting | `ToggleSwitch` | label the state clearly |
| Selection in a form or batch list | `CheckBox` | supports checked, unchecked, and optional indeterminate semantics |
| One visible option from a small set | grouped `RadioButton` controls | use `ComboBox` when space or option count makes scanning worse |
| One option from a compact list | `ComboBox` | it does not support multiple selection |
| Multiple options | `ListView`, `ItemsView`, checked list, or purpose-built flyout | keep selected values reviewable |
| Bounded continuous value | `Slider` | show current value and allow precise keyboard entry when needed |
| Rating | `RatingControl` | use only for genuine rating semantics |

Place labels where scan order remains clear under narrow widths, text scaling, and localization. Use `AutomationProperties.LabeledBy` when a separate label must be associated with a field. Mark required fields in text, not color alone. Provide constraints before entry, validate at a useful boundary such as blur or submit, and state both the problem and recovery.

Do not disable the primary action without explaining unmet requirements. Preserve user input on validation or network failure. For long forms, define draft, cancel, close, and unsaved-change behavior.

## 5. Commands and menus

Model a command once and expose it through suitable surfaces using `StandardUICommand`, `XamlUICommand`, or the project's `ICommand` pattern.

| Surface | Use |
|---|---|
| Primary page command | visible `Button` or `CommandBar` command |
| Document-centric application menus | `MenuBar` |
| Object-specific commands | `ContextFlyout`, preferably `CommandBarFlyout` when rich commands help |
| Extra or low-frequency commands | secondary `CommandBar` commands or overflow menu |
| Split default/alternate action | `SplitButton` |
| Menu-only action set | `DropDownButton` or `MenuFlyout` |
| Power-user path | `KeyboardAccelerator` plus tooltip/menu shortcut text |

Keep critical commands discoverable without hover or gestures. Include relevant contextual commands in a context menu so pointer, keyboard, touch, and assistive technology users have a common route. Use access keys for efficient Alt navigation and accelerators for repeated actions.

Use specific action labels such as “Delete 3 files” rather than “OK”. Keep destructive commands spatially separated and show consequence. Offer undo when the action is common and reversible.

## 6. Feedback and transient surfaces

| Need | Use | Guidance |
|---|---|---|
| Inline status, warning, or recoverable error | `InfoBar` | keep visible while action is required; do not assume automatic dismissal |
| First-use education anchored to UI | `TeachingTip` | show sparingly and never for routine status |
| Blocking decision or irreversible consequence | `ContentDialog` | ask only when the app cannot safely choose or offer undo |
| Contextual options or detail | `Flyout` | dismissible and connected to its source |
| Determinate work | `ProgressBar` | report meaningful progress |
| Indeterminate short wait | `ProgressRing` | keep surrounding context stable |
| Long/background work | in-page progress plus cancel/background affordance | do not trap users in a spinner |

For frequent destructive actions, prefer immediate completion plus undo over repeated confirmation. For truly destructive dialogs, make the title state the decision and use explicit button verbs.

Every async surface needs a success, failure, timeout, retry or alternate path, and cancellation strategy when cancellation is meaningful. Avoid white screens and layout jumps; retain the previous content or use a shape-matched placeholder.

## 7. Common page patterns

### Application shell

Use title bar, top-level navigation, page header, contextual commands, and a content frame or presenter. Keep title-bar drag regions separate from interactive navigation and search controls.

### Settings

Use Windows Community Toolkit `SettingsCard` and `SettingsExpander` only after verifying the installed Toolkit package. Group by user intent, add descriptions for non-obvious consequences, and make reversible preferences apply immediately. Use Apply, restart, or confirmation only when a change is expensive, delayed, security-sensitive, or not safely reversible.

### List/details

At wide widths, show list and details together. At compact widths, navigate between them while preserving list selection, scroll, filter, and keyboard focus. Define what happens when the selected item is deleted, filtered out, or fails to load.

### Form or editor

Use a predictable scan path, keep related controls together, align actions consistently, and reserve space for validation. Make save state explicit: saved, saving, unsaved, conflict, offline, or failed. Provide undo/redo for document-like work.

### Empty and error states

State what happened, why when known, and what the user can do next. Tailor empty states: first-use empty, filtered empty, permission denied, disconnected, and failed loading are different problems.

## 8. Control review checklist

- [ ] Each control matches the user's intent and exposes correct semantics.
- [ ] All APIs and dependencies exist in the project's versions.
- [ ] Navigation, selection, focus, and back behavior are defined.
- [ ] Contextual commands have a non-hover route.
- [ ] Collection virtualization and keyboard behavior are preserved.
- [ ] Forms retain input and provide actionable validation.
- [ ] Dialogs are limited to genuinely blocking decisions.
- [ ] Loading, empty, error, timeout, cancellation, and undo states are handled.

## 9. Official sources

- [Controls for Windows apps](https://learn.microsoft.com/windows/apps/develop/ui/controls/)
- [NavigationView](https://learn.microsoft.com/windows/apps/develop/ui/controls/navigationview)
- [TabView](https://learn.microsoft.com/windows/apps/develop/ui/controls/tab-view)
- [ItemsView](https://learn.microsoft.com/windows/apps/develop/ui/controls/itemsview)
- [Commanding](https://learn.microsoft.com/windows/apps/develop/ui/controls/commanding)
- [Dialogs and flyouts](https://learn.microsoft.com/windows/apps/design/controls/dialogs-and-flyouts/)
- [App settings guidelines](https://learn.microsoft.com/windows/apps/design/app-settings/guidelines-for-app-settings)
- [Archived WCT DataGrid status](https://learn.microsoft.com/dotnet/communitytoolkit/archive/windows/datagrid)