Avalonia Data Templates

Avalonia Data Templates

Overview

DataTemplates define how a data object is rendered as UI. They apply to:

• ItemsControl and subclasses (ListBox, TreeView, DataGrid) via ItemTemplate
• ContentControl and subclasses via ContentTemplate
• Any Content property — Avalonia walks up the template tree to find a matching DataTemplate

Template matching is by the data object's runtime type. First matching template in scope wins.

---

Inline DataTemplate

x:DataType enables compiled bindings inside the template. Every DataTemplate that uses compiled bindings must declare it.

---

ContentControl with DataTemplate

For multi-page navigation, app-level templates (see below) are more practical than per-ContentControl templates.

---

App-Level Templates (Global Auto-Selection)

In App.axaml, templates registered here apply everywhere in the application. Avalonia automatically uses the matching template when a ViewModel type appears as Content or as an item.

With this setup, a ContentControl binding to a ViewModel just works:

---

Template Scope Resolution Order

Avalonia searches for a matching DataTemplate in this order:

1. ContentControl.ContentTemplate or ItemsControl.ItemTemplate (explicit, highest priority)
2. Control.DataTemplates on the control itself
3. DataTemplates in parent controls, walking up the logical tree
4. Application.DataTemplates (global fallback)

First match wins. Order within a collection matters — put more specific types before base types.

---

DataTemplate Type Selector (IDataTemplate)

For conditional template selection based on runtime type or property values, implement IDataTemplate:

public class AnimalTemplateSelector : IDataTemplate
{
    // Set these from XAML
    public IDataTemplate? DogTemplate { get; set; }
    public IDataTemplate? CatTemplate { get; set; }

    public Control? Build(object? param) => param switch
    {
        Dog d => DogTemplate?.Build(d),
        Cat c => CatTemplate?.Build(c),
        _ => new TextBlock { Text = $"Unknown: {param}" }
    };

    public bool Match(object? data) => data is Dog or Cat;
}

---

FuncDataTemplate (Code-Only)

Useful in code-behind, custom controls, or when XAML is impractical:

// Simple
var template = new FuncDataTemplate((person, _) =>
    new TextBlock { Text = person.FullName });

// With bindings
var template = new FuncDataTemplate((person, scope) =>
{
    var tb = new TextBlock();
    tb.Bind(TextBlock.TextProperty, new Binding(nameof(PersonViewModel.FullName)));
    return tb;
});

myListBox.ItemTemplate = template;

---

Reusable Templates as Resources

Define once, reference many times:

---

TreeDataTemplate (Hierarchical / TreeView)

TreeDataTemplate extends DataTemplate with an ItemsSource binding for child nodes:

ViewModel:

public class TreeNode
{
    public string Name { get; set; } = "";
    public IImage? Icon { get; set; }
    public ObservableCollection Children { get; } = new();
}

Mixed types in a tree (files and folders):

public class AnimalTreeSelector : IDataTemplate
{
    public Control? Build(object? param) => param switch
    {
        FolderNode => /* build folder template */,
        FileNode => /* build file template */,
        _ => null
    };
    public bool Match(object? data) => data is FolderNode or FileNode;
}

---

ItemsControl Panel Customization

Change the layout panel used to arrange items:

---

Design-Time Data in Templates

---

Common Mistakes

• Missing x:DataType on DataTemplate — compiled bindings inside the template have no type context and fail to build. Every DataTemplate using {Binding} needs x:DataType.
• Wrong resource scope — a DataTemplate in Window.Resources is not visible to templates inside a nested UserControl. Each UserControl has its own resource scope. Put shared templates in Application.Resources or Application.DataTemplates.
• Using DataTemplate instead of TreeDataTemplate for tree data — DataTemplate renders the node content but does not provide an ItemsSource binding for children; TreeView will not recurse into children.
• Matching on interface type — Avalonia's automatic type-based template selection matches on the concrete runtime type, not interfaces. IDataTemplate.Match() must explicitly check for the concrete type, or register templates against the concrete type.
• Multiple templates for same type in same scope — if two DataTemplates in Application.DataTemplates have x:DataType="vm:PersonViewModel", the first one always wins. Remove duplicates or use keyed resources for multiple representations.
• Circular template reference — a DataTemplate that creates a ContentControl whose Content binds back to the same ViewModel type causes infinite recursion. Use a keyed template or break the cycle with a wrapper ViewModel.
• Setting both ItemTemplate and using auto-selection — an explicit ItemTemplate always takes precedence over Application.DataTemplates. Remove ItemTemplate to rely on global auto-selection.

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.