/winui-app

What This Reference Is For

Use this file when choosing controls, composing pages, or making a WinUI layout adapt well to different window sizes and input modes.

Prefer

• Built-in WinUI controls first.
• Native command surfaces such as CommandBar when the UI is grouping actions, toggles, and lightweight tool controls.
• Standard controls for common tasks: TextBox, NumberBox, ComboBox, ListView, GridView, ContentDialog, InfoBar, TeachingTip, TabView, NavigationView.
• Explicit scroll ownership for collection layouts. If the page already scrolls vertically, prefer giving a media shelf its own horizontal ScrollViewer and a simple horizontal panel.
• Responsive techniques such as reposition, resize, reflow, and show/hide.
• Layouts that remain usable when the window becomes narrow.
• A real phone-width plan when the app may be resized that far: fewer columns, reduced padding, simplified controls, and stacked content instead of compressed desktop rails.

Avoid

• Replacing standard WinUI controls with custom controls just to change appearance.
• Building custom toolbar rows out of generic layout panels when a stock CommandBar would cover the grouping cleanly.
• Hard-coded sizes that only look correct at one window width.
• Dense desktop-only layouts that break touch or keyboard workflows.
• Adding extra controls for local filtering or sorting when live updates and a simpler layout would better match the workflow.
• Nesting a scroll-owning GridView inside an outer page ScrollViewer without deciding which control owns scrolling; this often produces a single vertical column or awkward scroll conflicts instead of a horizontal media shelf.
• Wrapping list sections or card groups in an extra Border when the section header, spacing, and child surfaces already establish grouping.

Control Selection Guidance

• Forms and settings:
  • Prefer native controls first; add Toolkit settings controls only if the experience clearly benefits.
• Command surfaces:
  • Prefer CommandBar for grouped document, formatting, view, and page-level actions before composing a custom bar from Grid, StackPanel, Border, and loose buttons.
  • Prefer the CommandBar overflow model for secondary actions before splitting the command surface into multiple custom rows.
  • Fall back to a custom command layout only when a verified CommandBar limitation, an explicit product design requirement, or unusual content composition makes the native surface a poor fit.
• Large collections:
  • Prefer controls with virtualization-friendly behavior.
  • Use GridView when it owns the collection surface and its scrolling behavior is part of the intended experience.
  • For poster rails or other horizontal shelves inside a vertically scrolling page, prefer a horizontal ScrollViewer containing an ItemsControl or ItemsRepeater with a horizontal panel instead of a nested GridView.
  • Consider ItemsRepeater when the layout is custom and performance matters.
• Search and filtering:
  • Prefer a single search field with live updates for local or otherwise inexpensive filtering.
  • Add explicit apply, refresh, or mode-selection controls only when the underlying operation is expensive, remote, asynchronous, or semantically different.
• Dialogs and transient guidance:
  • Use ContentDialog for modal decisions.
  • Use InfoBar for persistent status.
  • Use TeachingTip for contextual onboarding.

Adaptive Layout Guidance

• Design with effective pixels, not fixed device assumptions.
• Make the smallest supported layout fully usable.
• Add density or multi-column views only when width allows.
• Use visual states, adaptive triggers, or layout state changes intentionally.
• Keep commands and primary content reachable after resize.
• Verify collection orientation and scrolling behavior at runtime. A shelf that looks horizontal in XAML can still render as a vertical stack once nested scroll regions are involved.
• When simplifying a dense section, remove redundant outer surfaces before adding more adaptive layout rules; fewer layers usually adapt more cleanly across breakpoints.
• Define breakpoint intent explicitly. Typical questions: when does a shelf become a stacked list, when does a footer drop nonessential controls, and when does the page stop behaving like a desktop canvas and become a single-column phone layout?
• Simplify as width shrinks. Prefer dropping secondary controls or moving them behind shell affordances over preserving every control at every breakpoint.
• When a page contains desktop-oriented horizontal shelves, add a phone-width alternative that stacks items vertically instead of relying on clipped rails and horizontal scrolling everywhere.

WinUI Gallery Anchors

• Control pages for built-in WinUI control usage
• Gallery home and shell pages for adaptive layout ideas
• Sample pages for title bar and system backdrop interactions with content layout

Review Checklist

• Did you choose the simplest built-in control that fits?
• Are search and filter controls no more complex than the data flow requires?
• Does the page remain usable when narrow?
• Can keyboard, mouse, and touch all reach the same core actions?
• Are spacing and hierarchy consistent across breakpoints?
• If the page mixes page scrolling with collection scrolling, is it obvious which control owns vertical scrolling and which one, if any, owns horizontal shelf scrolling?
• Are section containers doing real layout or surface work, or are some outer borders now redundant?
• At phone width, does the page read as a coherent single-column flow instead of a squeezed desktop layout?