WinUI Layout APIs

Layout Panels

WinUI provides a rich set of layout panels that automatically arrange their child elements. Understanding when to use each panel is key to efficient UI design.

Grid

The Grid panel arranges elements in rows and columns. It offers precise control over element placement and sizing, making it ideal for complex layouts.

<Grid RowDefinitions="Auto,*,Auto" ColumnDefinitions="100px,*">
    <TextBlock Grid.Row="0" Grid.Column="0" Text="Header"/>
    <ScrollViewer Grid.Row="1" Grid.Column="0" Grid.ColumnSpan="2">
        <!-- Content -->
    </ScrollViewer>
    <Button Grid.Row="2" Grid.Column="1" Content="Save"/>
</Grid>

StackPanel

The StackPanel arranges elements either horizontally or vertically in a single line. It's simple and efficient for linear arrangements.

<StackPanel Orientation="Vertical" Spacing="10">
    <TextBlock Text="Item 1"/>
    <TextBlock Text="Item 2"/>
    <TextBlock Text="Item 3"/>
</StackPanel>

RelativePanel

The RelativePanel allows you to position elements relative to each other or the panel itself. This is excellent for adaptive layouts.

<RelativePanel>
    <Button x:Name="SaveButton" Content="Save" RelativePanel.AlignBottomWithPanel="True" RelativePanel.AlignRightWithPanel="True"/>
    <TextBox RelativePanel.Below="SaveButton" RelativePanel.AlignLeftWithPanel="True" RelativePanel.AlignRightWithPanel="True"/>
</RelativePanel>

VariableSizedWrapGrid

This panel arranges items in a grid, allowing them to span multiple rows or columns. It's useful for tile-based or icon layouts.

Layout Properties

Beyond panels, several properties can be applied to individual UI elements to influence their layout behavior.

Margin and Padding

Margin defines the space outside an element's border, while Padding defines the space between the element's content and its border.

<TextBlock Text="Styled Text" Margin="10,5,10,5" Padding="5"/>

HorizontalAlignment and VerticalAlignment

These properties control how an element is aligned within its available space provided by its parent layout container.

<Button Content="Centered" HorizontalAlignment="Center" VerticalAlignment="Center"/>

Width, Height, MinWidth, MaxWidth, MinHeight, MaxHeight

These properties define the dimensional constraints of an element.

<Image Source="icon.png" Width="50" Height="50" MaxWidth="100"/>

HorizontalContentAlignment and VerticalContentAlignment

These properties control the alignment of content within controls like Button or TextBlock.

Attached Properties

Many layout-related behaviors are exposed through attached properties, particularly within specific layout panels.

Attached Property	Applies To	Description
Grid.Row, Grid.Column	Child elements of Grid	Specifies the row and column index for an element.
Grid.RowSpan, Grid.ColumnSpan	Child elements of Grid	Specifies how many rows or columns an element spans.
RelativePanel.AlignLeftWithPanel, etc.	Child elements of RelativePanel	Defines alignment relationships to the panel or other elements.

Custom Layout

For more advanced scenarios, you can create custom layout logic using techniques like deriving from Panel or using ArrangeOverride and MeasureOverride.