Skip to main content
This guide will walk you through creating a simple “Hello World” Avalonia application. You’ll learn the basic structure and see your first window in action.
Make sure you’ve completed the Installation guide before starting this tutorial.

​
Creating Your First Project

1

Create a New Avalonia Project

Open your terminal and create a new Avalonia MVVM application:
dotnet new avalonia.mvvm -o HelloAvalonia
cd HelloAvalonia
This creates a new project with the recommended MVVM (Model-View-ViewModel) architecture.
2

Explore the Project Structure

Your new project contains several important files:
HelloAvalonia/
├── App.axaml              # Application definition
├── App.axaml.cs           # Application code-behind
├── Program.cs             # Entry point
├── ViewModels/
│   ├── MainWindowViewModel.cs
│   └── ViewModelBase.cs
└── Views/
    └── MainWindow.axaml   # Main window definition
3

Run the Application

Build and run your application:
dotnet run
You should see a window appear with the default Avalonia UI!

​
Understanding the Code

Let’s examine the key components of an Avalonia application.

​
Program.cs - Entry Point

The entry point configures and starts your application:
Program.cs
using System;
using Avalonia;

class Program
{
    [STAThread]
    public static void Main(string[] args)
    {
        BuildAvaloniaApp()
            .StartWithClassicDesktopLifetime(args);
    }

    public static AppBuilder BuildAvaloniaApp()
        => AppBuilder.Configure<App>()
            .UsePlatformDetect()
            .UseSkia()
            .WithInterFont()
            .LogToTrace();
}
Key concepts:
  • AppBuilder.Configure<App>() - Creates the application builder with your App class
  • UsePlatformDetect() - Automatically detects and configures the platform (Windows, macOS, Linux)
  • UseSkia() - Uses Skia for rendering (cross-platform graphics library)
  • WithInterFont() - Includes the Inter font family
  • StartWithClassicDesktopLifetime() - Starts the application with desktop window support

​
App.axaml.cs - Application Class

The Application class manages your app’s lifecycle:
App.axaml.cs
using Avalonia;
using Avalonia.Controls.ApplicationLifetimes;
using Avalonia.Markup.Xaml;

public class App : Application
{
    public override void Initialize()
    {
        AvaloniaXamlLoader.Load(this);
    }

    public override void OnFrameworkInitializationCompleted()
    {
        if (ApplicationLifetime is IClassicDesktopStyleApplicationLifetime desktop)
        {
            desktop.MainWindow = new MainWindow
            {
                DataContext = new MainWindowViewModel()
            };
        }

        base.OnFrameworkInitializationCompleted();
    }
}
Key concepts:
  • Initialize() - Loads XAML resources and styles
  • OnFrameworkInitializationCompleted() - Called when the framework is ready
  • ApplicationLifetime - Manages the application lifecycle (different for desktop, mobile, browser)
  • MainWindow - Sets the initial window to display
  • DataContext - Connects the view to its ViewModel

​
MainWindow.axaml - Window Definition

XAML defines your UI structure:
MainWindow.axaml
<Window xmlns="https://github.com/avaloniaui"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:vm="using:HelloAvalonia.ViewModels"
        x:Class="HelloAvalonia.Views.MainWindow"
        x:DataType="vm:MainWindowViewModel"
        Title="Hello Avalonia"
        Width="450"
        Height="300">
    
    <Design.DataContext>
        <vm:MainWindowViewModel/>
    </Design.DataContext>

    <StackPanel HorizontalAlignment="Center" 
                VerticalAlignment="Center">
        <TextBlock Text="Welcome to Avalonia!" 
                   FontSize="24"
                   HorizontalAlignment="Center"/>
    </StackPanel>
</Window>
Key concepts:
  • Window - The top-level container
  • xmlns - XML namespaces for Avalonia controls
  • x:Class - Links to the code-behind file
  • x:DataType - Enables compiled bindings for better performance
  • Design.DataContext - Provides design-time data for the previewer

​
Building a Simple Interactive App

Let’s add some interactivity to make it more interesting.
1

Update the ViewModel

Open ViewModels/MainWindowViewModel.cs and add a property and command:
ViewModels/MainWindowViewModel.cs
using System.Windows.Input;
using CommunityToolkit.Mvvm.ComponentModel;
using CommunityToolkit.Mvvm.Input;

namespace HelloAvalonia.ViewModels;

public partial class MainWindowViewModel : ViewModelBase
{
    [ObservableProperty]
    private string _greeting = "Welcome to Avalonia!";

    [ObservableProperty]
    private int _clickCount = 0;

    [RelayCommand]
    private void SayHello()
    {
        ClickCount++;
        Greeting = $"Hello! Button clicked {ClickCount} time(s)";
    }
}
2

Update the View

Open Views/MainWindow.axaml and update the content:
Views/MainWindow.axaml
<Window xmlns="https://github.com/avaloniaui"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:vm="using:HelloAvalonia.ViewModels"
        x:Class="HelloAvalonia.Views.MainWindow"
        x:DataType="vm:MainWindowViewModel"
        Title="Hello Avalonia"
        Width="450"
        Height="300">
    
    <Design.DataContext>
        <vm:MainWindowViewModel/>
    </Design.DataContext>

    <StackPanel Spacing="10"
                HorizontalAlignment="Center" 
                VerticalAlignment="Center">
        
        <TextBlock Text="{Binding Greeting}" 
                   FontSize="20"
                   HorizontalAlignment="Center"
                   TextWrapping="Wrap"
                   Margin="20"/>
        
        <Button Content="Say Hello"
                Command="{Binding SayHelloCommand}"
                HorizontalAlignment="Center"
                Padding="20,10"/>
        
        <TextBlock Text="{Binding ClickCount, StringFormat='Clicks: {0}'}" 
                   HorizontalAlignment="Center"
                   FontSize="14"
                   Opacity="0.7"/>
    </StackPanel>
</Window>
3

Run Your Interactive App

Run the application again:
dotnet run
Click the “Say Hello” button and watch the greeting update!

​
Key Concepts Explained

​
Data Binding

Data binding connects UI elements to ViewModel properties: 
<TextBlock Text="{Binding Greeting}" />
When Greeting changes in the ViewModel, the TextBlock automatically updates.

​
Commands

Commands handle user interactions: 
<Button Content="Say Hello" Command="{Binding SayHelloCommand}" />
The button executes SayHelloCommand when clicked.

​
Observable Properties

Using [ObservableProperty] from CommunityToolkit.Mvvm automatically generates change notification code: 
[ObservableProperty]
private string _greeting = "Welcome to Avalonia!";
This creates a public Greeting property that notifies the UI when changed.

​
Layout Controls

Avalonia provides various layout controls: 
<!-- Stacks children vertically or horizontally -->
<StackPanel Orientation="Vertical" Spacing="10">
    <TextBlock Text="First" />
    <TextBlock Text="Second" />
    <TextBlock Text="Third" />
</StackPanel>

​
Styling Your App

Add styles to customize appearance:
App.axaml
<Application xmlns="https://github.com/avaloniaui"
             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
             x:Class="HelloAvalonia.App">
    <Application.Styles>
        <FluentTheme />
        
        <Style Selector="Button">
            <Setter Property="Background" Value="#007ACC" />
            <Setter Property="Foreground" Value="White" />
            <Setter Property="CornerRadius" Value="4" />
        </Style>
        
        <Style Selector="Button:pointerover">
            <Setter Property="Background" Value="#005A9E" />
        </Style>
    </Application.Styles>
</Application>

​
Developer Tools

Enable DevTools for debugging:
Program.cs
public static AppBuilder BuildAvaloniaApp()
    => AppBuilder.Configure<App>()
        .UsePlatformDetect()
        .UseSkia()
        .WithInterFont()
        .LogToTrace()
        .WithDeveloperTools();  // Enable DevTools
Press F12 while running to inspect the visual tree, properties, and more.

​
Next Steps

Build a Complete App

Create a full-featured application with multiple views and real functionality

Learn XAML

Dive deeper into XAML markup and layout systems

Explore Controls

Discover the full range of built-in Avalonia controls

Understanding MVVM

Master the MVVM pattern for clean, maintainable code
Continue to Building Your First App for a more comprehensive tutorial!

Build docs developers (and LLMs) love

Get started for freeTalk to us