11 KiB
WinUI controls and desktop patterns
Contents
- Selection method
- Navigation and window shell
- Collections and structured data
- Input controls and forms
- Commands and menus
- Feedback and transient surfaces
- Common page patterns
- Control review checklist
- Official sources
1. Selection method
Choose controls by semantics and built-in behavior:
- Identify whether the user is navigating, selecting, invoking, editing, comparing, or inspecting.
- Prefer the control that already implements the expected keyboard, focus, selection, automation, and theme behavior.
- Check availability against the exact Windows App SDK or Toolkit version.
- Customize styles before templates; replace the control only if its interaction model is wrong.
- 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.