Avalonia Pro Max/layout Patterns

Layout Patterns

Breakpoints

Avalonia desktop windows have no fixed viewport, so define your own breakpoint conventions and react in code-behind or via OnSizeChanged. Recommended scale:

| Name | Width | Typical | |---|---|---| | Compact | = 640 && e.NewSize.Width = 1024 && e.NewSize.Width = 1440); }

Then style by class:
```xml

For more granular containers, use ContainerQuery (see avalonia-styling).

---

Layout Templates

App Shell — Sidebar + Content + Right Panel

Hide the right rail on compact/medium:

 Border:nth-child(3)">
  

Master-Detail with SplitView

For mobile-style adaptive: bind DisplayMode to a converter on window width — Inline on wide, Overlay on compact.

Dashboard Grid (Cards)

For responsive columns, swap to WrapPanel with min card widths:

…and set MinWidth="280" MaxWidth="360" on the card.

For powerful auto-grid behavior, use AvaloniaAutoGrid or custom Layout with ItemsRepeater.

Settings Page

MaxWidth="720" keeps reading length sane on ultrawide.

Centered Single-Column (auth, onboarding)

---

Navigation Pattern Selection

| Pattern | Use when | Avalonia mechanism | |---|---|---| | Sidebar nav (vertical) | Desktop app, ≤8 top-level destinations | SplitView or FluentAvalonia NavigationView PaneDisplayMode="Left" | | Top tab nav | ≤5 destinations, content-focused | TabControl | | Bottom nav | Mobile, ≤5 destinations | FluentAvalonia NavigationView PaneDisplayMode="LeftMinimal" (mobile-styled) or custom Grid with RadioButtons | | Hamburger drawer | Many destinations + secondary nav | SplitView DisplayMode="Overlay" with toggle | | Command palette | Power users, search-driven | Custom modal with TextBox + filtered ListBox; bind Ctrl+K | | Breadcrumb | Hierarchical content (file system, settings) | Custom ItemsControl with separator template |

Never mix sidebar + bottom nav at the same hierarchy level.

Adaptive nav (single source of truth)

NavigationView.PaneDisplayMode = window.Bounds.Width switch
{
     NavigationViewPaneDisplayMode.LeftMinimal,
     NavigationViewPaneDisplayMode.LeftCompact,
    _      => NavigationViewPaneDisplayMode.Left
};

---

Spacing Rhythm in Layouts

• Page padding: 24–32 px on desktop, 16 px on compact.
• Section spacing: Space6 (24 px) between major sections, Space4 (16 px) within.
• Card padding: PaddingCard (20 px).
• StackPanel.Spacing instead of per-child Margin (cleaner, less drift).

Avoid Margin and Padding collision — pick one.

---

ScrollViewer Discipline

• Wrap only the scrollable region, not the whole window — let headers/footers stay fixed.
• One vertical scroll axis per view; nested scroll regions break wheel/trackpad UX.
• Set HorizontalScrollBarVisibility="Disabled" on vertical lists to prevent accidental horizontal scroll.
• For long lists, use a VirtualizingStackPanel (default in ListBox/ItemsRepeater) — never a regular StackPanel for 100+ items.

For grid virtualization, use ItemsRepeater with StackLayout or UniformGridLayout.

---

Window Chrome

Hints:

• PreferSystemChrome — keep OS controls (recommended).
• NoChrome — fully custom (provide your own min/max/close buttons).
• OSXThickTitleBar — macOS thicker bar with traffic lights inset.

Reserve 40 px top safe area for the drag region. Add a DragRegion element with IsHitTestVisible="True" and listen for pointer drag if going chromeless.

---

Mobile-Specific (Avalonia.Mobile)

• Use SafeAreaPadding from TopLevel.InsetsManager:

``csharp var insets = TopLevel.GetTopLevel(this)!.InsetsManager; insets.DisplayEdgeToEdge = true; ``

• Bottom nav must respect home-indicator inset.
• Touch targets ≥44×44 dp.
• One vertical scroll axis only.

---

Common Mistakes

• Fixed pixel widths on the whole layout — breaks at small windows. Use * Grid columns.
• StackPanel for a 500-item list — laggy; use ListBox/ItemsRepeater (virtualized).
• Two vertical scroll regions stacked — wheel doesn't know which to scroll.
• No MaxWidth on long-form text — line length exceeds 90 chars and hurts readability.
• Sidebar always visible at 800px window — content gets cramped; collapse to overlay.
• Putting nav in a Window and content in a Window separately — single-window app should use SplitView/NavigationView.
• Hardcoded margins like 12,8,15,4 — break the spacing scale; use tokens.
• Forgetting RowDefinitions="Auto,*" — content expands wrongly.
• Mixing DockPanel and Grid semantics in the same panel — confusing layout. Pick one root layout per scope.

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.