avalonia-data-binding
Use when writing data bindings, compiled bindings, converters, MultiBinding, collection views, validation, or binding to commands in Avalonia. Covers binding modes, path syntax, DataContext, built-in and custom converters, FallbackValue, DataValidationException, and debugging techniques.
linuxdevel · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add linuxdevel/Avalonia-skills --skill avalonia-data-bindingAbout this skill
name: avalonia-data-binding description: Use when writing data bindings, compiled bindings, converters, MultiBinding, collection views, validation, or binding to commands in Avalonia. Covers binding modes, path syntax, DataContext, built-in and custom converters, FallbackValue, DataValidationException, and debugging techniques.
Avalonia Data Binding
Overview
(12.0+) compiled bindings are on by default (AvaloniaUseCompiledBindingsByDefault defaults true). {Binding} without x:DataType fails to compile. Compiled bindings are verified at build time and generate no reflection. Opt out per scope with x:CompileBindings="False", per binding with {ReflectionBinding}, or globally with <AvaloniaUseCompiledBindingsByDefault>false</AvaloniaUseCompiledBindingsByDefault>.
(11.x) compiled bindings are opt-in: set <AvaloniaUseCompiledBindingsByDefault>true</AvaloniaUseCompiledBindingsByDefault> or x:CompileBindings="True"; otherwise {Binding} is reflection-based and {CompiledBinding} must be explicit.
Binding API in C# code
| 11.x | 12.0+ |
|---|---|
IBinding | BindingBase (ReflectionBinding, CompiledBinding, TemplateBinding, IndexerBinding derive from it) |
InstancedBinding | BindingExpressionBase |
new Binding("Path") | new ReflectionBinding("Path") (Binding kept for compatibility = ReflectionBinding) or CompiledBinding |
// (12.0+) typed compiled binding from a lambda
var b = CompiledBinding.Create((Item item) => item.Value);
Binding plugins (BindingPlugins) are removed in 12; data-annotations validation is off by default (11.x: on).
Binding Modes
| Mode | Direction | Updates |
|---|---|---|
OneWay | Source → Target | On source change |
TwoWay | Source ↔ Target | On either change |
OneTime | Source → Target | Once at bind time |
OneWayToSource | Target → Source | On target change |
Default | Per-property default | Typically TwoWay for input controls, OneWay for display |
Basic Binding Syntax
<!-- Compiled binding — requires x:DataType on scope root -->
<Window xmlns:vm="using:MyApp.ViewModels"
x:DataType="vm:MainViewModel">
<TextBox Text="{Binding Name}"/>
<TextBlock Text="{Binding Name, Mode=OneWay}"/>
<TextBlock Text="{Binding Name, StringFormat='Hello, {0}!'}"/>
</Window>
<!-- Opt out per-binding (reflection binding) -->
<TextBox Text="{Binding Name, x:CompileBindings=False}"/>
<!-- Explicit compiled binding syntax (default in 12.0+; required in 11.x unless compiled-by-default is set) -->
<TextBox Text="{CompiledBinding Name}"/>
Binding Path Syntax
| Syntax | Meaning |
|---|---|
{Binding Name} | Property on DataContext |
{Binding Address.Street} | Nested property path |
{Binding [0]} | Indexer |
{Binding [key]} | Dictionary indexer |
{Binding .} | DataContext itself |
{Binding #controlName.Property} | Named control in same scope |
{Binding $parent.Property} | Nearest parent control |
{Binding $parent[Window].Property} | Nearest parent of type Window |
{Binding $parent[1].Property} | Parent N levels up |
{Binding $self.Property} | The control itself |
{Binding $root.Property} | Root of logical tree |
DataContext
Inherits down the logical tree. Child controls automatically receive the parent DataContext unless overridden.
<!-- Set in XAML -->
<Window DataContext="{x:Static vm:DesignData.Main}"
x:DataType="vm:MainViewModel">
<!-- Design-time only data context -->
<Design.DataContext>
<vm:MainViewModelDesign/>
</Design.DataContext>
// Set in code-behind
public MainWindow()
{
InitializeComponent();
DataContext = new MainViewModel();
}
x:DataType informs the compiler what type the DataContext is. Required for every scope (Window, UserControl, DataTemplate) that uses compiled bindings.
Converters
Built-in (namespace Avalonia.Data.Converters)
| Converter | Usage |
|---|---|
BooleanToVisibilityConverter | bool → IsVisible (rarely needed; bind IsVisible to bool directly) |
StringConverters.IsNullOrEmpty | string → bool |
StringConverters.IsNotNullOrEmpty | string → bool |
ObjectConverters.IsNull | object → bool |
ObjectConverters.IsNotNull | object → bool |
FuncValueConverter<TIn,TOut> | Inline lambda converter |
<TextBlock IsVisible="{Binding Name, Converter={x:Static StringConverters.IsNotNullOrEmpty}}"/>
FuncValueConverter (inline, no class needed)
// In ViewModel or resource file
public static readonly FuncValueConverter<int, string> CountToLabel =
new(count => count == 1 ? "item" : "items");
<TextBlock Text="{Binding Count, Converter={x:Static vm:Converters.CountToLabel}}"/>
Custom IValueConverter
public class InverseBoolConverter : IValueConverter
{
public static readonly InverseBoolConverter Instance = new();
public object? Convert(object? value, Type targetType, object? parameter, CultureInfo culture)
=> value is bool b ? !b : BindingOperations.DoNothing;
public object? ConvertBack(object? value, Type targetType, object? parameter, CultureInfo culture)
=> Convert(value, targetType, parameter, culture);
}
<!-- Register as resource -->
<Window.Resources>
<converters:InverseBoolConverter x:Key="InverseBool"/>
</Window.Resources>
<Button IsEnabled="{Binding IsBusy, Converter={StaticResource InverseBool}}"/>
Converter with Parameter
<TextBlock Text="{Binding Price, Converter={StaticResource CurrencyConverter}, ConverterParameter=USD}"/>
MultiBinding
<TextBlock>
<TextBlock.Text>
<MultiBinding StringFormat="{}{0} {1}">
<Binding Path="FirstName"/>
<Binding Path="LastName"/>
</MultiBinding>
</TextBlock.Text>
</TextBlock>
`FuncMultiValueConverter<
Read the complete source ↗