Avalonia Layout

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

| Panel | Arranges children | Use when | |---|---|---| | Grid | In defined rows/columns | Complex layouts, forms, dashboards | | StackPanel | Linearly (H or V) | Toolbars, lists, vertical forms | | WrapPanel | Linearly, wraps to next row/col | Tag clouds, icon grids, badge lists | | DockPanel | Docked to edges + fill center | App shell, menu+content+statusbar | | Canvas | Absolute x/y positions | Drawing surfaces, overlays, diagrams | | UniformGrid | Equal-size cells, auto rows/cols | Grids of same-size items | | RelativePanel | Relative to siblings or panel | Adaptive layouts, dynamic alignment |

Grid

Sizing Modes

| Syntax | Meaning | |---|---| | * | Proportional — takes remaining space | | 2* | Takes 2× the share of * | | Auto | Sized to content | | 200 | Fixed pixel size |

Basic Grid

Login Form Example

SharedSizeGroup

Keeps columns at equal widths across separate Grids:

StackPanel

Spacing was added in Avalonia 11. Do not use Margin on each child for spacing — use Spacing on the panel.

DockPanel

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

Canvas

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

Alignment & Spacing Reference

HorizontalAlignment / VerticalAlignment

| Value | Behavior | |---|---| | Stretch (default) | Fills available space | | Left / Top | Aligns to start edge | | Center | Centers in available space | | Right / Bottom | Aligns to end edge |

Margin / Padding Syntax

| Syntax | Meaning | |---|---| | "8" | All four sides = 8 | | "8,4" | Left+Right=8, Top+Bottom=4 | | "8,4,8,4" | Left=8, Top=4, Right=8, Bottom=4 |

Size Constraints

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

Responsive Layouts

Proportional Grid (Most Common)

Adaptive Layout with ContainerQuery (Avalonia 12)

For truly responsive behavior, use code-behind or reactive bindings that respond to Bounds changes:

// In code-behind
this.GetObservable(BoundsProperty)
    .Subscribe(bounds =>
    {
        if (bounds.Width 
    
        
    

Common Mistakes

| Mistake | Symptom | Fix | |---|---|---| | Canvas inside StackPanel with no explicit size | Canvas children invisible (zero height/width) | Set explicit Width/Height on the Canvas | | * sizing inside StackPanel | Star column/row collapses | StackPanel gives infinite space — * has no bound. Use Grid instead. | | Forgetting LastChildFill="False" in DockPanel | Last element stretches unexpectedly | Add LastChildFill="False" and size last child explicitly | | Margin on root element of UserControl | Outer margin bleeds outside control bounds | Use Padding on the UserControl root, not Margin | | HorizontalAlignment="Stretch" with explicit Width | Width is ignored or conflicted | Remove explicit Width or change alignment to Left/Right | | Dock order mistakes in DockPanel | Elements appear in wrong positions | Dock elements in correct top→bottom order; last undocked child fills | | Setting Height="Auto" on StackPanel | No effect — StackPanel is always Auto height by default | Remove redundant property; set explicit height on parent if constraint needed | | Nested ScrollViewer without fixed outer height | Inner scroll never activates | Ensure outer container has a bounded height (Height, MaxHeight, or star row in Grid) |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: linuxdevel
• Source: linuxdevel/Avalonia-skills
• License: MIT

Install and usage instructions live in the source repository linked above.