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. (12.0+) compiled bindings are ON by default (AvaloniaUseCompiledBindingsByDefault=true): {Binding} maps to CompiledBinding, so x:DataType is required wherever bindings are used. In 11.x compiled bindings are opt-in ({CompiledBinding} / x:CompileBindings="True"). Escape hatch: {ReflectionBinding Path} or x:CompileBindings="False".

File Structure

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

<Window xmlns="https://github.com/avaloniaui"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:vm="using:MyApp.ViewModels"
        x:Class="MyApp.MainWindow"
        x:DataType="vm:MainWindowViewModel"
        Title="My App"
        Width="800" Height="450">

    <TextBlock Text="{Binding Greeting}" />

</Window>

Corresponding code-behind:

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

namespace MyApp;

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

XML Namespaces

Namespace Syntax

Common Namespaces

Markup Extensions

x: Attributes

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;
    }
}

<!-- MyView.axaml -->
<UserControl xmlns="https://github.com/avaloniaui"
             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
             x:Class="MyApp.Views.MyView">
    <Button x:Name="myButton"
            Content="Click Me"
            Click="OnButtonClick" />
</UserControl>

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 { DataContext = viewModel };
// (12.0+) explicit types; `new Binding(...)` is a compat alias of ReflectionBinding
textBox.Bind(TextBox.TextProperty, new ReflectionBinding(nameof(MainViewModel.Name)));
textBox.Bind(TextBox.TextProperty, CompiledBinding.Create((MainViewModel vm) => vm.Name)); // (12.0+) AOT/trim safe
// (11.x)
textBox.Bind(TextBox.TextProperty, new Binding("Name"));

Gesture Events (12.0+)

Gesture attached events live directly on InputElement — drop the Gestures. prefix (Gestures is no longer public):

<Border Pinch="OnPinch" ScrollGesture="OnScroll" Tapped="OnTapped" />
<!-- (11.x) <Border Gestures.Pinch="OnPinch" Gestures.ScrollGesture="OnScroll" /> -->

Resource Dictionaries

<Application.Resources>
    <ResourceDictionary>
        <ResourceDictionary.MergedDictionaries>
            <ResourceInclude Source="avares://MyApp/Assets/Colors.axaml"/>
        </ResourceDictionary.MergedDictionaries>
        <SolidColorBrush x:Key="BrandBrush" Color="#5B4FCF"/>
    </ResourceDictionary>
</Application.Resources>

<!-- Colors.axaml -->
<ResourceDictionary xmlns="https://github.com/avaloniaui"
                    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
    <Color x:Key="BrandColor">#5B4FCF</Color>
</ResourceDictionary>

Runtime XAML for Previewers and Editors

For runtime-loaded documents, relative includes, existing root instances, diagnostics, and source locations, read references/runtime-xaml.md. It covers Avalonia 12.1 and 11.3; normal application views should keep the compiled InitializeComponent() path.

Common Mistakes