Layout & Panels

WPF uses a layout system based on a slot model. Every FrameworkElement is treated as a rectangle that is slotted into a space its parent gives it. The size of that slot is computed from the available screen space, the element’s size constraints, its margin and padding, and the individual behavior of the parent Panel. An element does not have to fill its slot (the LayoutInformation.GetLayoutSlot method returns the slot, which is frequently larger than the visible content).

Layout is recursive and runs in two passes over the tree, always on the UI thread:

Neither pass is called by application code in normal use; the layout system queues them when something invalidates the tree and runs them before the next render. The members involved are:

Three consequences of the model are the source of most layout questions:

When layout runs repeatedly for the same invalidation (an element changes its own size inside SizeChanged or LayoutUpdated, which changes its size again), WPF detects the loop and throws an InvalidOperationException whose message reports a layout cycle. The fix is to remove the dependency of the size on itself rather than to catch the exception.

Source: Layout

Before a panel’s own logic runs, FrameworkElement applies its sizing properties around MeasureOverride and ArrangeOverride. These are the properties that every element in every panel shares.

Thickness values in XAML accept one number (all sides), two numbers (horizontal, vertical) or four numbers in the order left, top, right, bottom: Margin="8", Margin="8,4", Margin="8,4,8,0".

Source: Alignment, Margins, and Padding Overview

A panel is an element derived from System.Windows.Controls.Panel whose job is to arrange its children. Panel provides the Children collection (the content property, so child elements go directly between the tags), the Background brush, the Panel.ZIndex attached property for stacking children that overlap and, for authors of custom panels, InternalChildren, which is Children plus the items generated by data binding when the panel hosts the items of an ItemsControl. Panels make heavy use of attached properties such as Grid.Row and DockPanel.Dock: the child declares a value that its parent panel reads during layout.

UniformGrid lives in System.Windows.Controls.Primitives; the others are in System.Windows.Controls. The official panel overview names Canvas, DockPanel, Grid, StackPanel, VirtualizingStackPanel and WrapPanel as the panels designed to build application UI; UniformGrid is a utility panel used inside controls and templates.

Source: Panel

Grid is the workhorse of WPF layout and the right root for almost every window. It divides its area into rows and columns declared with RowDefinitions and ColumnDefinitions; a child chooses its cell with the attached properties Grid.Row and Grid.Column (both default to 0) and may span several with Grid.RowSpan and Grid.ColumnSpan. Several children can share a cell, in which case they overlap in document order (lower Panel.ZIndex first).

StackPanel arranges children in a single line. Its Orientation is Vertical by default. Along the orientation it measures children with an infinite size, so each child reports its natural extent and the stack grows as long as needed; across the orientation, children with Stretch alignment fill the panel’s width (or height). A StackPanel never scrolls: put a ScrollViewer outside it (see below) or the content is clipped when the window is too small.

WPF’s StackPanel has no Spacing property (WinUI 3’s does). Space is created with Margin on the children, or with an implicit Style for the child type so that the value is written once:

Source: StackPanel

The three commands are generated by [RelayCommand] methods of the view model; they are shown here only for the layout. StackPanel is the right panel for a few controls, and the wrong one for a list: it creates every child at once, unlike VirtualizingStackPanel, which is what item controls use by default.

DockPanel docks each child to one edge of the space still left, in the order the children appear. The attached property DockPanel.Dock takes Left, Top, Right or Bottom (the default is Left). LastChildFill is true by default, so the last child ignores its Dock and fills what remains. Order is meaningful: a child docked to the top first takes the full width, one docked to the left first takes the full height.

Source: DockPanel

Compared with a Grid, DockPanel is a good fit for window chrome (toolbar, status bar, side bar, content) and uses less code, but it gives no control over proportions. The main window above uses a Grid because the middle row must split by columns.

WrapPanel places children one after another and starts a new line at the edge of the panel (the line direction depends on Orientation: Horizontal by default, Vertical flows top to bottom). ItemWidth and ItemHeight force every child into a uniform cell (the default NaN lets each child keep its own size). Each line’s height is that of its tallest child. If the WrapPanel is measured with an infinite width (inside a StackPanel with Horizontal orientation or a horizontally scrolling ScrollViewer), it never wraps. Typical uses are tag strips and thumbnail galleries:

Source: Panel

The ItemsPanel property swaps the panel an ItemsControl uses to host its generated containers; the container list and its virtualization are discussed on Lists, Grids & Trees. A WrapPanel in ItemsPanel is not virtualized, so it suits tens of items, not thousands.

Canvas positions children with the attached properties Canvas.Left, Canvas.Top, Canvas.Right and Canvas.Bottom (a child with none of them set sits at the top-left corner; when both Left and Right are set, Left wins). It measures children with an unlimited size, so they get their natural size, and it reports a desired size of zero to its parent; a Canvas with Width and Height unset therefore collapses to nothing unless its parent stretches it. Children are not constrained, repositioned or clipped when the window resizes, and the Canvas is the cheapest panel for layout. Use it for overlays and drawing surfaces, not for forms.

Source: Canvas

The Canvas sits on top of the Image in the same Grid cell, so the badge floats over the cover; the Canvas stretches to the cell (its parent gave it a slot), while its single child is positioned from the right edge. The BoolToVisibility converter is a resource as on the Resources & Resource Dictionaries page.

UniformGrid (in System.Windows.Controls.Primitives) divides its area into equal cells. Rows and Columns set the dimensions; if both are 0 the panel makes a square-ish grid that fits the children, and if only one is set the other is computed. FirstColumn leaves leading cells in the first row empty. Every cell has the same size, which makes it suitable for a bar of equally sized buttons:

Source: Panel

Because all cells are equal, one long label can force every cell to be as wide. Where that is unacceptable, use a Grid with star columns, which allows MinWidth.

Two decorators change the constraint their content is measured with rather than arranging children themselves.

ScrollViewer measures its content with an infinite size in each direction whose scroll bar is not Disabled and gives it the viewport size in the others. HorizontalScrollBarVisibility and VerticalScrollBarVisibility take Disabled (no scrolling, content is constrained to the viewport), Auto (the bar appears when needed), Hidden (scrolls without a visible bar) or Visible. The defaults are Disabled horizontally and Visible vertically. CanContentScroll chooses logical scrolling (by item, only when the content implements IScrollInfo, as virtualizing panels do) or physical scrolling (by device-independent unit, the default for a ScrollViewer placed manually). The details pane above uses HorizontalScrollBarVisibility="Disabled", so its text wraps to the 300-unit width instead of scrolling sideways.

Viewbox has exactly one child and scales it to fit. Stretch is Uniform by default (keep the aspect ratio), with None, Fill (distort) and UniformToFill (fill and crop); StretchDirection is Both by default, and UpOnly or DownOnly restrict it. It is useful for a fixed-design widget such as a chart or a splash image that must shrink with the window, but scaling applies to text and strokes too, so it is not a replacement for responsive layout.

Source: ScrollViewer

Wrapping text needs a finite width: TextWrapping="Wrap" in a vertically scrolling ScrollViewer works because horizontal scrolling is Disabled; with Auto the text would be measured at infinite width and never wrap.

WPF positions in device-independent units, so at 125 % or 150 % scaling an element edge can fall between two physical pixels, and anti-aliasing then draws blurry one-pixel borders and uneven gaps between neighbouring elements. Two mechanisms address this, at different levels:

Layout rounding can make the sum of rounded children differ by a pixel from the parent, so exact comparisons of sizes should allow a tolerance. WinUI 3 rounds layout by default (UseLayoutRounding defaults to true there).

Source: Layout

When no built-in panel arranges children the way a design needs, derive from Panel and override MeasureOverride and ArrangeOverride. The contract is small, but strict:

The official how-to defines a deliberately trivial PlotPanel that puts one child at the fixed position (50, 50); it shows the two overrides but not wrapping, infinite constraints or a bindable property. The ShelfPanel below is the bookshelf of the scenario: it places children left to right, starts a new shelf when the row is full, and aligns the covers of each shelf to its bottom edge, as books rest on a plank.

Source: How to: Create a Custom Panel Element

The panel is used as the ItemsPanel of an ItemsControl (or ListBox) bound to the books. WPF creates the panel from the ItemsPanelTemplate and marks it as the items host, which is why InternalChildren is the collection to use:

Source: Panel

Points to notice in ShelfPanel, each tied to the contract above:

All three stacks use a parent-driven layout, but the vocabulary and defaults differ. Porting a WPF layout to WinUI 3 is mostly mechanical for Grid, StackPanel and Canvas; panels that exist only in WPF need a replacement.

The WinUI 3 and Windows Forms entries are summarised from those stacks' own documentation and are covered in depth on their pages; the WPF column is the subject of this one.

Source: Panel

The layout engine is the same engine that shipped in .NET Framework 3.0: porting a WPF project to .NET does not change Measure, Arrange, the built-in panels or their defaults, and layouts that rendered correctly keep their geometry (apart from small differences in text rendering and the theme).

Source: What’s new in WPF for .NET 10

Layout is a recursive, intensive process: the cost grows with the number of children and with the complexity of the panels that own them, and each time a child changes size or position it can trigger a new pass. The official guidance and practical corollaries are:

To inspect the result, use Live Visual Tree and Live Property Explorer in Visual Studio (see the Development Environment & Tooling page): selecting an element shows its margin, its size and its alignment properties, and the debugging toolbar in the running window can display layout adorners for the selection. Grid.ShowGridLines is a quick check of track boundaries in a debug build.

Source: Optimizing Performance: Layout and Design