StackPanel, WrapPanel and DockPanel

Three panels, three simple ideas

The Grid can do almost any layout, but it needs row and column definitions. For many small jobs a simpler panel is easier to write and easier to read. This lesson covers three of them:

• StackPanel puts children in a single line, one after another.
• WrapPanel does the same, but starts a new line when it runs out of room.
• DockPanel sticks children to the edges (top, bottom, left, right) and gives the rest of the space to the last child.

Each one follows the size, margin and alignment rules you learned in Layout Basics. Real windows usually mix several panels, nested inside each other, and the end of this lesson shows how.

StackPanel

A StackPanel stacks its children. By default it stacks them vertically, top to bottom, like plates in a pile.

<StackPanel Margin="16">
    <TextBlock Text="Monthly summary" FontSize="18" />
    <TextBlock Text="Food: 120.00" />
    <TextBlock Text="Transport: 45.50" />
    <TextBlock Text="Bills: 300.00" />
</StackPanel>

There are no rows to define and no attached properties to set. The order in the XAML is the order on screen.

Orientation

Set Orientation="Horizontal" to place the children side by side, left to right:

<StackPanel Orientation="Horizontal" HorizontalAlignment="Right" Margin="8">
    <Button Content="Cancel" Padding="16,4" Margin="0,0,8,0" />
    <Button Content="Save" Padding="16,4" />
</StackPanel>

This is the classic way to make a row of dialog buttons. The Margin on the first button keeps a small gap between them, because StackPanel itself adds no space between items.

How StackPanel sizes its children

In a vertical StackPanel, every child is stretched to the full width, but gets only the height it asks for. In a horizontal one it is the other way round: full height, but only the width it needs.

The important detail: a vertical StackPanel offers its children unlimited height. It says “take as much height as you like”. That has two effects you need to know:

1. A child with VerticalAlignment="Stretch" does not fill the remaining space, because there is no “remaining” space in an infinite direction.
2. A ListBox or ScrollViewer inside a vertical StackPanel never shows a scroll bar. It thinks it has endless room, so it simply grows taller than the window.

<!-- Problem: the list grows past the bottom of the window and never scrolls -->
<StackPanel>
    <TextBlock Text="Expenses" />
    <ListBox x:Name="ExpenseList" />
</StackPanel>

The fix is to use a Grid (or a DockPanel) for the outer layout, so the list gets a limited height. You will see scrolling in detail in ScrollViewer and Viewbox.

Rule of thumb: use StackPanel for small groups of items that will never need to scroll, like a few buttons or a few lines of text.

WrapPanel

A WrapPanel lays children out in a line, and when the next child does not fit, it wraps onto a new line. It works like words in a paragraph.

<WrapPanel Margin="8">
    <Button Content="Food" Margin="4" Padding="12,4" />
    <Button Content="Transport" Margin="4" Padding="12,4" />
    <Button Content="Bills" Margin="4" Padding="12,4" />
    <Button Content="Fun" Margin="4" Padding="12,4" />
    <Button Content="Other" Margin="4" Padding="12,4" />
</WrapPanel>

Make the window narrow and the buttons flow onto a second row. This is great for tags, filter chips, colour swatches and photo thumbnails.

Orientation and item sizes

WrapPanel also has Orientation. The default is Horizontal (fill a row, then wrap down). Vertical fills a column, then wraps to the right.

To make every item the same size, set ItemWidth and ItemHeight:

<!-- Every child gets a 100 x 40 slot, so the rows line up like a grid -->
<WrapPanel ItemWidth="100" ItemHeight="40">
    <Button Content="Food" Margin="4" />
    <Button Content="Transport" Margin="4" />
    <Button Content="Bills" Margin="4" />
</WrapPanel>

Without ItemWidth, each child is as wide as its content, so the rows have a ragged edge.

DockPanel

A DockPanel lets each child dock (attach) to one edge of the panel. Think of building a room: first you put a shelf along the top wall, then a desk along the left wall, and whatever floor is left in the middle is for the last piece of furniture.

Children choose an edge with the attached property DockPanel.Dock, which can be Top, Bottom, Left or Right:

<DockPanel>
    <TextBlock DockPanel.Dock="Top" Text="Header" Background="SteelBlue" Foreground="White" Padding="8" />
    <TextBlock DockPanel.Dock="Bottom" Text="Status: ready" Background="WhiteSmoke" Padding="8" />
    <TextBlock DockPanel.Dock="Left" Text="Categories" Background="AliceBlue" Padding="8" Width="120" />
    <TextBlock Text="Main content fills the rest" Padding="8" />
</DockPanel>

LastChildFill

By default the last child fills all the space that is left, whatever its DockPanel.Dock value. That is controlled by LastChildFill, which is True by default. Set LastChildFill="False" if you want the last child to dock to an edge like the others and leave empty space in the middle.

<!-- A toolbar: one button on the left, two on the right, a gap in between -->
<DockPanel LastChildFill="False">
    <Button DockPanel.Dock="Left" Content="New" />
    <Button DockPanel.Dock="Right" Content="Help" />
    <Button DockPanel.Dock="Right" Content="Settings" />
</DockPanel>

Order matters

Each child takes its edge from the space that is still free when its turn comes. So the order of the children changes the result.

<!-- Top first: the header goes across the full width -->
<DockPanel>
    <Border DockPanel.Dock="Top" Height="40" Background="SteelBlue" />
    <Border DockPanel.Dock="Left" Width="100" Background="AliceBlue" />
    <Border Background="White" />
</DockPanel>

<!-- Left first: the sidebar goes the full height, the header sits beside it -->
<DockPanel>
    <Border DockPanel.Dock="Left" Width="100" Background="AliceBlue" />
    <Border DockPanel.Dock="Top" Height="40" Background="SteelBlue" />
    <Border Background="White" />
</DockPanel>

Try both and compare. In the first, the header is wider. In the second, the sidebar is taller. If a child has no DockPanel.Dock, it docks Left.

Choosing the right panel

You can always nest them. A DockPanel for the window shell, with a horizontal StackPanel of buttons docked at the top and a Grid in the middle, is very common.

Adding children from code

Every panel has a Children collection. You can add elements to it from code-behind. This is handy when the number of items is not known until the app runs:

private void AddTagButton_Click(object sender, RoutedEventArgs e)
{
    var tag = new Button
    {
        Content = TagNameBox.Text,
        Margin = new Thickness(4),
        Padding = new Thickness(12, 4, 12, 4)
    };
    TagPanel.Children.Add(tag);   // TagPanel is a WrapPanel with x:Name="TagPanel"
}

Thickness is the C# type behind Margin and Padding. new Thickness(4) means 4 on every side, and the four number version is left, top, right, bottom, the same as in XAML.

To set an attached property such as DockPanel.Dock from code, use DockPanel.SetDock(element, Dock.Top).

Later, in Binding to Collections, you will let WPF create the items for you from a list of data instead of adding controls by hand.

Common mistakes

• A list inside a StackPanel that does not scroll. The vertical StackPanel gives it infinite height. Use a Grid row with * instead.
• Expecting StackPanel to add spacing. It does not. Add a Margin to the children.
• Forgetting LastChildFill. The last child of a DockPanel grows to fill the space, which is a surprise if you wanted it to sit on an edge.
• Putting the “fill” element first in a DockPanel. The filling child must be last, otherwise it takes all the space and the others get nothing.
• Deep nesting of StackPanels to fake a grid. If items must line up in columns, use a Grid.

Quick recap

• StackPanel places children in one line. Orientation chooses vertical (default) or horizontal.
• A vertical StackPanel offers infinite height, so lists inside it never scroll.
• WrapPanel flows children onto new lines when space runs out. ItemWidth and ItemHeight give equal slots.
• DockPanel docks children to edges with DockPanel.Dock. The last child fills the rest unless LastChildFill="False".
• In a DockPanel, the order of children decides who gets the corners.
• Every panel has a Children collection you can add to from code-behind.