Maui Data Binding

.NET MAUI Data Binding

Don't specify redundant binding modes

Set Mode explicitly only when overriding the default. Most properties already have the right default:

<!-- ✅ Defaults — omit Mode -->
<Label Text="{Binding Score}" />           <!-- OneWay is the default -->
<Entry Text="{Binding UserName}" />        <!-- TwoWay is the default -->
<Switch IsToggled="{Binding DarkMode}" />  <!-- TwoWay is the default -->

<!-- ✅ Override when needed -->
<Label Text="{Binding Title, Mode=OneTime}" />
<Entry Text="{Binding SearchQuery, Mode=OneWayToSource}" />

<!-- ❌ Redundant — just noise -->
<Label Text="{Binding Score, Mode=OneWay}" />
<Entry Text="{Binding UserName, Mode=TwoWay}" />

Compiled bindings — x:DataType placement rules

Compiled bindings are 8–20× faster than reflection-based bindings. Enable with x:DataType.

Place `x:DataType` only where `BindingContext` is set:

1. Page root — where you assign BindingContext. 2. DataTemplate — which creates a new binding scope.

Do not scatter x:DataType on child elements. Adding x:DataType="x:Object" on children to "escape" compiled bindings is an anti-pattern — it disables compile-time checking and reintroduces reflection. To opt out for a single binding, use x:DataType="{x:Null}" on that element (see also: maui-xaml-authoring skill).

<!-- ✅ Correct: x:DataType only where BindingContext is set -->
<ContentPage x:DataType="vm:MainViewModel">
    <VerticalStackLayout>
        <Label Text="{Binding Title}" />
        <Slider Value="{Binding Progress}" />
    </VerticalStackLayout>
</ContentPage>

<!-- ❌ Wrong: x:DataType scattered on children -->
<ContentPage x:DataType="vm:MainViewModel">
    <VerticalStackLayout>
        <Label Text="{Binding Title}" />
        <Slider x:DataType="x:Object" Value="{Binding Progress}" />
    </VerticalStackLayout>
</ContentPage>

DataTemplate always needs its own `x:DataType`:

<CollectionView ItemsSource="{Binding People}">
    <CollectionView.ItemTemplate>
        <DataTemplate x:DataType="model:Person">
            <Label Text="{Binding FullName}" />
        </DataTemplate>
    </CollectionView.ItemTemplate>
</CollectionView>

Treat compiler warnings as errors in CI

<WarningsAsErrors>XC0022;XC0025</WarningsAsErrors>

.NET 9+ compiled code bindings

Fully AOT-safe, no reflection:

label.SetBinding(Label.TextProperty,
    static (PersonViewModel vm) => vm.FullName);

entry.SetBinding(Entry.TextProperty,
    static (PersonViewModel vm) => vm.Age,
    mode: BindingMode.TwoWay,
    converter: new IntToStringConverter());

Threading caveat

MAUI automatically marshals PropertyChanged to the UI thread — you can raise it from any thread. However, direct ObservableCollection mutations (Add/Remove) from background threads may still crash:

// ✅ Safe for PropertyChanged
await Task.Run(() => Items = LoadData());

// ⚠️ ObservableCollection.Add — dispatch to UI thread
MainThread.BeginInvokeOnMainThread(() => Items.Add(newItem));

Performance tips

• Compiled bindings eliminate reflection — always prefer them.
• NativeAOT / trimming: Reflection-based bindings break under trimming. Compiled bindings (XAML x:DataType or code SetBinding with lambdas) are trimmer- and AOT-safe.
• Use `OneTime` mode for truly static data to skip change-tracking registration.
• Avoid complex converter chains in hot paths — pre-compute values in the ViewModel instead.

Data Binding API Reference

Binding Modes

BindingContext and Property Paths

• Every BindableObject inherits BindingContext from its parent unless explicitly set.
• Property paths support dot notation and indexers:

<Label Text="{Binding Address.City}" />
<Label Text="{Binding Items[0].Name}" />

• Set BindingContext in XAML or code-behind:

<ContentPage xmlns:vm="clr-namespace:MyApp.ViewModels"
             x:DataType="vm:MainViewModel">
    <ContentPage.BindingContext>
        <vm:MainViewModel />
    </ContentPage.BindingContext>
</ContentPage>

IValueConverter

Implement IValueConverter with Convert (source → target) and ConvertBack (target → source):

public class IntToBoolConverter : IValueConverter
{
    public object? Convert(object? value, Type targetType,
        object? parameter, CultureInfo culture)
        => value is int i && i != 0;

    public object? ConvertBack(object? value, Type targetType,
        object? parameter, CultureInfo culture)
        => value is true ? 1 : 0;
}

Declaring converters in XAML resources

<ContentPage.Resources>
    <local:IntToBoolConverter x:Key="IntToBool" />
</ContentPage.Resources>

<Switch IsToggled="{Binding Count, Converter={StaticResource IntToBool}}" />

ConverterParameter

ConverterParameter is always passed as a string. Parse it inside Convert:

<Label Text="{Binding Score, Converter={StaticResource ThresholdConverter},
              ConverterParameter=50}" />

int threshold = int.Parse((string)parameter);

StringFormat

Use Binding.StringFormat for simple display formatting without a converter:

<Label Text="{Binding Price, StringFormat='Total: {0:C2}'}" />
<Label Text="{Binding DueDate, StringFormat='{0:MMM dd, yyyy}'}" />

Note: Wrap the format string in single quotes when it contains commas or braces.

Multi-Binding

Combine multiple source values with IMultiValueConverter:

<Label>
    <Label.Text>
        <MultiBinding Converter="{StaticResource FullNameConverter}"
                      StringFormat="{}{0}">
            <Binding Path="FirstName" />
            <Binding Path="LastName" />
        </MultiBinding>
    </Label.Text>
</Label>

public class FullNameConverter : IMultiValueConverter
{
    public object Convert(object[] values, Type targetType,
        object parameter, CultureInfo culture)
    {
        if (values.Length == 2 && values[0] is string first && values[1] is string last)
            return $"{first} {last}";
        return string.Empty;
    }

    public object[] ConvertBack(object value, Type[] targetTypes,
        object parameter, CultureInfo culture)
        => throw new NotSupportedException();
}

Relative Bindings

<!-- Square box: Height = Width -->
<BoxView WidthRequest="100"
         HeightRequest="{Binding Source={RelativeSource Self}, Path=WidthRequest}" />

Binding Fallbacks

• FallbackValue – used when the binding path cannot be resolved or the converter throws.
• TargetNullValue – used when the bound value is null.

<Label Text="{Binding MiddleName, TargetNullValue='(none)',
              FallbackValue='unavailable'}" />
<Image Source="{Binding AvatarUrl, TargetNullValue='default_avatar.png'}" />