Avalonia Controls Layout

Avalonia Layout Controls

Overview

Layout controls are containers that position and constrain child controls. See avalonia-layout for general sizing/alignment concepts. This skill covers the container control APIs.

---

Border

Single-child container. Adds background, border, rounded corners, padding, and shadows.

| Property | Type | Notes | |---|---|---| | Background | IBrush | Fill color | | BorderBrush | IBrush | Border color | | BorderThickness | Thickness | 1 or 1,2,1,2 (L,T,R,B) | | CornerRadius | CornerRadius | 8 or 8,0,8,0 (TL,TR,BR,BL) | | Padding | Thickness | Inner spacing | | BoxShadow | BoxShadows | Drop shadow(s) | | Child | Control | Single child only |

> Important: Border only accepts one child. Wrap multiple children in a Panel, StackPanel, or Grid.

---

ScrollViewer

Adds scrollbars to content that overflows its bounds.

| Property | Type | Notes | |---|---|---| | HorizontalScrollBarVisibility | ScrollBarVisibility | Auto, Visible, Hidden, Disabled | | VerticalScrollBarVisibility | ScrollBarVisibility | Auto, Visible, Hidden, Disabled | | Offset | Vector | Programmatic scroll position | | Extent | Size | Total content size | | Viewport | Size | Visible area size | | AllowAutoHide | bool | Hides scrollbar when not hovering | | HorizontalSnapPointsType | SnapPointsType | Snap behavior |

ScrollBarVisibility values:

| Value | Behavior | |---|---| | Auto | Shows when content overflows | | Visible | Always shown | | Hidden | Never shown, but scrolling still works | | Disabled | Disables scrolling in that direction |

// Programmatic scroll
scrollViewer.Offset = new Vector(0, 500);

// Scroll to end
scrollViewer.ScrollToEnd();

// Subscribe to scroll events
scrollViewer.ScrollChanged += (s, e) =>
{
    bool atBottom = scrollViewer.Offset.Y >= scrollViewer.ScrollBarMaximum.Y;
};

> Pitfall: ScrollViewer inside StackPanel never scrolls because StackPanel gives infinite height. Fix: use a Grid row with Height="*" or set an explicit Height on the ScrollViewer.

---

SplitView

Two-region layout: a collapsible pane and main content area.

| Property | Type | Notes | |---|---|---| | IsPaneOpen | bool | TwoWay — controls pane visibility | | OpenPaneLength | double | Width when expanded | | CompactPaneLength | double | Width when compact (icon-only) | | DisplayMode | SplitViewDisplayMode | See table below | | PanePlacement | SplitViewPanePlacement | Left (default), Right | | Pane | object | Pane content | | Content | object | Main content area |

DisplayMode values:

| Mode | Behavior | |---|---| | Overlay | Pane overlaps content when open | | Inline | Pane pushes content when open | | CompactOverlay | Shows CompactPaneLength strip; expands over content | | CompactInline | Shows CompactPaneLength strip; expands pushing content |

> Note: Pane and Content are set via XAML property element syntax, not as items in a Children collection.

---

Expander

Collapsible section with a header.

| Property | Type | Notes | |---|---|---| | Header | object | Always-visible header (string or XAML) | | IsExpanded | bool | TwoWay — controls expand state | | ExpandDirection | ExpandDirection | Down (default), Up, Left, Right | | ContentTransition | IPageTransition | Animation for expand/collapse |

---

Viewbox

Scales a single child to fill available space while optionally preserving aspect ratio.

| Property | Type | Notes | |---|---|---| | Stretch | Stretch | See table below | | StretchDirection | StretchDirection | Both, UpOnly, DownOnly |

Stretch values:

| Value | Behavior | |---|---| | None | No scaling | | Fill | Stretches to fill, ignores aspect ratio | | Uniform | Scales uniformly to fit (default) | | UniformToFill | Scales uniformly to fill, may clip |

---

Panel Variants Reference

For full layout concepts see avalonia-layout. Quick API reference:

Grid

StackPanel

| Property | Notes | |---|---| | Orientation | Vertical (default), Horizontal | | Spacing | Uniform gap between items |

WrapPanel

DockPanel

UniformGrid

Canvas

---

Common Mistakes

| Mistake | Fix | |---|---| | Multiple children inside Border | Wrap in StackPanel or Grid — Border.Child accepts exactly one element | | ScrollViewer inside StackPanel not scrolling | StackPanel gives infinite height; use Grid with Height="*" row or set explicit height on ScrollViewer | | SplitView Pane content not showing | Set via ` property element, not as a child item | | Expander header cut off | Set MinHeight on Expander or ensure parent doesn't constrain height to 0 | | Viewbox making content blurry | Viewbox uses bitmap scaling for raster content; use vector (PathIcon, Canvas paths) for crisp results | | Canvas not respecting size in layout | Canvas reports desired size as 0×0 by default; set explicit Width/Height on the Canvas element | | Grid items overlapping | Every child needs explicit Grid.Row/Grid.Column`; without them all go to row 0, col 0 |

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.