Avalonia Layout

Overview

Avalonia layout uses a two-pass measure/arrange system. Every control has Margin (space outside the control), Padding (space inside), HorizontalAlignment, and VerticalAlignment. Layout is done with Panel subclasses — choose the panel that matches the arrangement model.

Panel Quick Reference

Grid

Sizing Modes

Basic Grid

<Grid RowDefinitions="Auto,*,Auto"
      ColumnDefinitions="200,*">

    <!-- Header spans full width -->
    <Border Grid.Row="0" Grid.ColumnSpan="2" Background="Navy" Height="50"/>

    <!-- Sidebar -->
    <ListBox Grid.Row="1" Grid.Column="0"/>

    <!-- Main content -->
    <ScrollViewer Grid.Row="1" Grid.Column="1">
        <StackPanel Margin="16" Spacing="8"/>
    </ScrollViewer>

    <!-- Footer spans full width -->
    <Border Grid.Row="2" Grid.ColumnSpan="2" Padding="8,4"/> <!-- no built-in StatusBar control; use Border/StackPanel -->

</Grid>

Login Form Example

<Grid RowDefinitions="Auto,Auto,Auto,Auto"
      ColumnDefinitions="120,*"
      Width="320"
      HorizontalAlignment="Center"
      VerticalAlignment="Center">

    <TextBlock Grid.Row="0" Grid.Column="0"
               Text="Username:"
               VerticalAlignment="Center"
               Margin="0,0,8,8"/>
    <TextBox Grid.Row="0" Grid.Column="1"
             Margin="0,0,0,8"/>

    <TextBlock Grid.Row="1" Grid.Column="0"
               Text="Password:"
               VerticalAlignment="Center"
               Margin="0,0,8,8"/>
    <TextBox Grid.Row="1" Grid.Column="1"
             PasswordChar="●"
             Margin="0,0,0,16"/>

    <Button Grid.Row="2" Grid.Column="0" Grid.ColumnSpan="2"
            Content="Sign In"
            HorizontalAlignment="Right"/>

</Grid>

SharedSizeGroup

Keeps columns at equal widths across separate Grids:

<StackPanel Grid.IsSharedSizeScope="True">
    <Grid ColumnDefinitions="Auto,*">
        <TextBlock Grid.Column="0"
                   Text="First Name:"
                   SharedSizeGroup="Labels"/>
        <TextBox Grid.Column="1"/>
    </Grid>
    <Grid ColumnDefinitions="Auto,*">
        <TextBlock Grid.Column="0"
                   Text="Email Address:"
                   SharedSizeGroup="Labels"/>
        <TextBox Grid.Column="1"/>
    </Grid>
</StackPanel>

StackPanel

<!-- Vertical (default) with spacing -->
<StackPanel Spacing="8" Margin="16">
    <Button Content="First"/>
    <Button Content="Second"/>
    <Button Content="Third"/>
</StackPanel>

<!-- Horizontal toolbar -->
<StackPanel Orientation="Horizontal" Spacing="4">
    <Button Content="New"/>
    <Button Content="Open"/>
    <Separator/>
    <Button Content="Save"/>
</StackPanel>

Spacing works in 11.3, 12.0 and 12.1. Do not use Margin on each child for spacing — use Spacing on the panel.

DockPanel

<DockPanel LastChildFill="True">

    <!-- Top menu bar -->
    <Menu DockPanel.Dock="Top">
        <MenuItem Header="File"/>
    </Menu>

    <!-- Bottom status bar -->
    <Border DockPanel.Dock="Bottom" Padding="8,4"> <!-- no built-in StatusBar control -->
        <TextBlock Text="Ready"/>
    </Border>

    <!-- Left sidebar -->
    <TreeView DockPanel.Dock="Left" Width="200"/>

    <!-- Center fills remaining space (LastChildFill) -->
    <TextEditor/>

</DockPanel>

Dock order matters: elements are docked in the order they appear. The last child fills remaining space when LastChildFill="True" (default).

Canvas

<Canvas Width="400" Height="300">
    <!-- Positioned absolutely -->
    <Rectangle Canvas.Left="50" Canvas.Top="30"
               Width="100" Height="60"
               Fill="CornflowerBlue"/>

    <Ellipse Canvas.Left="200" Canvas.Top="100"
             Width="80" Height="80"
             Fill="Tomato"
             ZIndex="1"/>

    <TextBlock Canvas.Right="10" Canvas.Bottom="10"
               Text="Bottom-right anchor"/>
</Canvas>

Canvas.Left/Top/Right/Bottom are attached properties. Use ZIndex to control paint order.

Alignment & Spacing Reference

HorizontalAlignment / VerticalAlignment

Margin / Padding Syntax

<!-- Uniform -->
<Button Margin="8" Content="A"/>

<!-- Horizontal, Vertical -->
<Button Margin="16,8" Content="B"/>

<!-- Left, Top, Right, Bottom -->
<Button Margin="16,8,0,8" Content="C"/>

Size Constraints

<TextBox Width="200"
         MinWidth="100"
         MaxWidth="400"
         Height="32"/>

Avoid setting both Width and HorizontalAlignment="Stretch" — they conflict. Use one or the other.

Responsive Layouts

Proportional Grid (Most Common)

<!-- Two-column layout: sidebar + content -->
<Grid ColumnDefinitions="250,*">
    <NavigationPane Grid.Column="0"/>
    <ContentArea Grid.Column="1"/>
</Grid>

Adaptive Layout with ContainerQuery (11.x and 12.x)

Mark a container, then host a ContainerQuery (not nested inside a Style) in an ancestor's Styles. Styles inside can't affect the container or its ancestors.

<Grid>
    <Grid.Styles>
        <ContainerQuery Name="host" Query="max-width:600">
            <Style Selector="UniformGrid#cards">
                <Setter Property="Columns" Value="1"/>
            </Style>
        </ContainerQuery>
    </Grid.Styles>
    <Border Container.Name="host" Container.Sizing="Width">
        <UniformGrid x:Name="cards" Columns="3"/>
    </Border>
</Grid>

For logic that styles can't express, react to Bounds changes in code:

// In code-behind
this.GetObservable(BoundsProperty)
    .Subscribe(bounds =>
    {
        if (bounds.Width < 600)
        {
            mainGrid.ColumnDefinitions = new ColumnDefinitions("*");
            // move items to single column
        }
        else
        {
            mainGrid.ColumnDefinitions = new ColumnDefinitions("*,*");
        }
    });

ScrollViewer for Overflow

<ScrollViewer HorizontalScrollBarVisibility="Disabled"
              VerticalScrollBarVisibility="Auto">
    <StackPanel Spacing="8" Margin="16">
        <!-- content taller than viewport -->
    </StackPanel>
</ScrollViewer>

Version Notes

• Layout panels/Grid/StackPanel APIs are unchanged between 11.3 and 12.x.
• (12.0+) Layoutable Thickness properties (Margin, Padding, ...) reject NaN/infinite values. TextBlock no longer rounds its size when UseLayoutRounding=false.
• (12.0+) LayoutManager class removed (→ ILayoutManager); ILayoutRoot removed. Don't cast the root visual to TopLevel — use TopLevel.GetTopLevel(visual).
• (12.0+) Layoutable.GetMaxSizeFromConstraint is protected (override in custom panels/controls).

Common Mistakes