Avalonia Xaml

Avalonia XAML

Overview

Avalonia uses .axaml extension (not .xaml) to avoid Visual Studio WPF tooling conflicts. XAML is optional; full code-only UI is supported. Avalonia 12 enables compiled bindings by default — x:DataType is required on root elements where bindings are used.

File Structure

Every .axaml file requires the Avalonia root namespace and language namespace:

Corresponding code-behind:

// MainWindow.axaml.cs
using Avalonia.Controls;

namespace MyApp;

public partial class MainWindow : Window
{
    public MainWindow()
    {
        InitializeComponent();
    }
}

XML Namespaces

Namespace Syntax

| Syntax | Use case | Example | |---|---|---| | using: | Same solution assemblies (preferred) | xmlns:vm="using:MyApp.ViewModels" | | clr-namespace: | External assemblies (requires ;assembly=) | xmlns:ctrl="clr-namespace:MyLib.Controls;assembly=MyLib" | | URI | Framework namespaces | xmlns="https://github.com/avaloniaui" |

Common Namespaces

| Prefix | URI / Syntax | Purpose | |---|---|---| | (default) | https://github.com/avaloniaui | All Avalonia controls | | x: | http://schemas.microsoft.com/winfx/2006/xaml | XAML language features | | vm: | using:MyApp.ViewModels | ViewModel types | | conv: | using:MyApp.Converters | Converter classes | | sys: | using:System | System types (Math, String, etc.) |

Markup Extensions

| Extension | Purpose | Example | |---|---|---| | {Binding} | Runtime data binding | Text="{Binding Name}" | | {CompiledBinding} | Compile-time checked binding | Text="{CompiledBinding Name}" | | {StaticResource} | One-time resource lookup | Fill="{StaticResource AccentBrush}" | | {DynamicResource} | Live resource lookup (updates on change) | Background="{DynamicResource SystemControlBackground}" | | {x:Static} | Static field/property | Value="{x:Static sys:Math.PI}" | | {x:Type} | Type reference | TargetType="{x:Type Button}" | | {x:Null} | Null literal | Tag="{x:Null}" | | {OnPlatform} | Per-platform value | FontSize="{OnPlatform 12, macOS=14}" | | {OnFormFactor} | Per-form-factor value | Width="{OnFormFactor 200, Mobile=100}" |

x: Attributes

| Attribute | Purpose | Notes | |---|---|---| | x:Class | Links AXAML to code-behind partial class | Must match namespace + class name exactly | | x:Name | Names control for code-behind access | Generates a typed field in partial class | | x:Key | Resource dictionary key | Required for resources in ` | | x:DataType | Compiled binding root type | Required on root or DataTemplate when using compiled bindings | | x:CompileBindings | Enable/disable compiled bindings per scope | x:CompileBindings="False"` to opt out |

Code-Behind Pattern

// MyView.axaml.cs
using Avalonia.Controls;

namespace MyApp.Views;

public partial class MyView : UserControl
{
    public MyView()
    {
        InitializeComponent();
    }

    // Access named controls via generated fields
    private void OnButtonClick(object sender, RoutedEventArgs e)
    {
        // myButton is generated from x:Name="myButton" in AXAML
        myButton.IsEnabled = false;
    }
}

Code-Only UI (No XAML)

Preferred for: dynamic control creation, headless testing, generated UIs.

using Avalonia;
using Avalonia.Controls;
using Avalonia.Layout;

var window = new Window
{
    Title = "Code Only",
    Width = 400,
    Height = 300,
    Content = new StackPanel
    {
        Spacing = 8,
        Margin = new Thickness(16),
        Children =
        {
            new TextBlock { Text = "Hello, Avalonia!" },
            new Button
            {
                Content = "Click Me",
                HorizontalAlignment = HorizontalAlignment.Left
            }
        }
    }
};

Bindings in code:

var textBox = new TextBox();
textBox.Bind(TextBox.TextProperty, new Binding("Name"));
// Or with compiled binding (requires source object):
textBox[!TextBox.TextProperty] = viewModel.WhenAnyValue(x => x.Name)
    .ToBinding(); // with ReactiveUI

Resource Dictionaries

    #5B4FCF

Common Mistakes

| Mistake | Fix | |---|---| | Using .xaml extension | Rename to .axaml | | Missing xmlns="https://github.com/avaloniaui" | Add as first attribute on root element | | clr-namespace: without ;assembly= for external lib | xmlns:x="clr-namespace:MyLib;assembly=MyLib" | | Compiled binding error: "Cannot resolve symbol" | Add x:DataType="vm:MyViewModel" to root or DataTemplate | | x:Name field not accessible in code-behind | Ensure file is .axaml and InitializeComponent() is called | | {StaticResource} not found at runtime | Resource must be defined before use in document order | | {DynamicResource} for performance-sensitive paths | Use {StaticResource} when resource never changes |

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.