Data Binding Guide
MewUI data binding is delegate based and free of reflection, so it stays compatible with Native AOT.
1. Core Concepts
Section titled “1. Core Concepts”Binding without reflection
Section titled “Binding without reflection”WPF and WinUI write what to bind to as a string and resolve it with reflection at run time. MewUI writes the same thing as code.
<!-- WPF --><TextBlock Text="{Binding UserName}" /><TextBlock Text="{Binding Customer.City}" /><TextBlock Text="{Binding Orders[0].Title}" /><TextBlock Text="{Binding Total, StringFormat=N0}" />// MewUInew TextBlock().Bind(TextBlock.TextProperty, vm, x => x.UserName);new TextBlock().Bind(TextBlock.TextProperty, vm, x => x.Customer.City);new TextBlock().Bind(TextBlock.TextProperty, vm, x => x.Orders[0].Title);new TextBlock().Bind(TextBlock.TextProperty, vm, x => x.Total, total => $"{total:N0}");A nested path is code as well, not a string. The compiler checks every step, a change notification is attached at every step, and replacing an intermediate object reconnects everything below it (section 4).
As the last line shows, WPF’s StringFormat and Converter collapse into one thing here. Every value transformation is a convert delegate (section 3.3).
What follows from strings becoming code:
- Native AOT compatible: there is no reflection, so trimming is safe
- Compile time checking: a misspelled property or a type mismatch fails the build
- IntelliSense and refactoring: completion works, and renaming a property renames the binding
Binding modes
Section titled “Binding modes”public enum BindingMode{ OneWay, // source to control TwoWay, // both directions}The target property decides the default. Input properties such as TextBox.TextProperty default to TwoWay, display properties such as Label.TextProperty default to OneWay. An explicit mode argument wins.
What happens when a binding resolves to TwoWay but has no way to write back depends on the API. A converted ObservableValue binding without convertBack degrades to OneWay. An INotifyPropertyChanged source and a path binding throw. Telling you immediately beats leaving an input control silently one-way.
2. Source Kinds
Section titled “2. Source Kinds”A binding source is one of three things. All of them use the same API from section 3.
2.1 ObservableValue<T>
Section titled “2.1 ObservableValue<T>”A container that holds one value and announces changes, so you write no notification code.
var name = new ObservableValue<string>("default");
string current = name.Value;name.Value = "new value";
name.Changed += () => Console.WriteLine("changed");A coerce delegate constrains the value.
var percent = new ObservableValue<double>(50, v => Math.Clamp(v, 0, 100));percent.Value = 150; // 100percent.Value = -10; // 02.2 INotifyPropertyChanged view models
Section titled “2.2 INotifyPropertyChanged view models”A view model with ordinary properties works as a source once it implements INotifyPropertyChanged. The subscription is weak, so a long-lived view model does not keep the view alive.
sealed class UserViewModel : INotifyPropertyChanged{ private string _name = "";
public event PropertyChangedEventHandler? PropertyChanged;
public string Name { get => _name; set { _name = value; PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(nameof(Name))); } }}A notification whose property name is null or empty means “everything changed” and re-reads the value.
2.3 A MewProperty on another MewObject
Section titled “2.3 A MewProperty on another MewObject”Connects one control’s property straight to another’s.
new ProgressBar().Bind(RangeBase.ValueProperty, slider, RangeBase.ValueProperty);2.4 Choosing between them
Section titled “2.4 Choosing between them”ObservableValue<T> writes the notification code for you, which suits a view model that only serves MewUI. INotifyPropertyChanged suits an existing MVVM view model or one shared with another framework. You can mix both in one view model, and mix them within a single path (section 4).
A plain property with no notification cannot be a source. It is read once and then stops updating.
3. Attaching a Binding
Section titled “3. Attaching a Binding”3.1 Fluent shorthands
Section titled “3.1 Fluent shorthands”Frequently bound properties have a dedicated method that takes an ObservableValue<T>.
new TextBox().BindText(name) // two-waynew Label().BindText(name) // one-waynew Label().BindText(count, c => $"count: {c}") // convertednew CheckBox().BindIsChecked(isChecked)new Slider().BindValue(volume)new Button().BindIsVisible(isVisible).BindIsEnabled(isEnabled)3.2 Bind and SetBinding
Section titled “3.2 Bind and SetBinding”The general API works with any MewProperty<T>. Bind returns the element for chaining; SetBinding is the lower level method offering the same overloads.
// ObservableValueelement.Bind(Control.BackgroundProperty, colorSource);
// INotifyPropertyChanged view modelnew Label().Bind(Label.TextProperty, vm, x => x.Name);
// A TwoWay target is two-way as written; the write path comes from the getter expressionnew TextBox().Bind(TextBox.TextProperty, vm, x => x.Name);
// Pass a setter only to decide how the write happensnew TextBox().Bind(TextBox.TextProperty, vm, x => x.Name, (owner, value) => owner.Name = value.Trim());
// An ObservableValue reached through an owner. This overload does not require INotifyPropertyChanged.new Label().Bind(Label.TextProperty, settings, x => x.Caption);
// Another element's propertyelement.Bind(TextBlock.TextProperty, otherElement, Window.TitleProperty);setter is optional. Without one, the write path is built from the getter expression at compile time. Pass one to normalize or validate on the way in, and it takes precedence.
A build where the generator does not run (see the SDK requirement in 4.1) has no such synthesis. There, binding a TwoWay target without a setter throws. Pass a setter or state mode: BindingMode.OneWay.
A getter over an INotifyPropertyChanged source must read exactly one member, because the observed property name comes from that expression. No parameter is offered for passing the name directly, so the name and the value it reads cannot drift apart. To walk more than one member, see section 4.
3.3 Conversion
Section titled “3.3 Conversion”When the source type and the target type differ, pass convert. TwoWay also needs convertBack.
// A number as display textnew Label().Bind(Label.TextProperty, vm, x => x.Temperature, value => $"{value:0.0} C");
// Inverted boolean: hide the results while loadingresults.Bind(UIElement.IsVisibleProperty, vm, x => x.IsLoading, loading => !loading);
// Presence of a value as visibilitybanner.Bind(UIElement.IsVisibleProperty, vm, x => x.ErrorMessage, message => !string.IsNullOrEmpty(message));
// Two-way needs convertBacktextBox.Bind(TextBase.TextProperty, intSource, convert: i => i.ToString(), convertBack: s => int.TryParse(s, out var v) ? v : 0);With an ObservableValue source and a visibility or enabled target, the BindIsVisible(source, convert) and BindIsEnabled(source, convert) shorthands do the same job.
Where WPF has you write a BooleanToVisibilityConverter or its inverted twin, here it is one lambda. There is no converter class to define and no resource to register.
Keep every computation in convert. Computation inside the getter leaves nothing to decide what should be observed.
3.4 Putting it together
Section titled “3.4 Putting it together”class LoginViewModel{ public ObservableValue<string> Username { get; } = new(""); public ObservableValue<bool> RememberMe { get; } = new(false); public ObservableValue<string> ErrorMessage { get; } = new(""); public ObservableValue<bool> IsLoading { get; } = new(false);
public void Login() { if (string.IsNullOrEmpty(Username.Value)) { ErrorMessage.Value = "Enter a user name"; return; }
IsLoading.Value = true; }}new StackPanel() .Vertical() .Spacing(8) .Children( new TextBox() .Placeholder("User name") .BindText(vm.Username),
new CheckBox() .Content("Stay signed in") .BindIsChecked(vm.RememberMe),
new Label() .Foreground(Color.FromRgb(200, 60, 60)) .BindText(vm.ErrorMessage),
new Button() .Content("Sign in") .OnCanClick(() => !vm.IsLoading.Value) .OnClick(() => vm.Login()))4. Nested Paths
Section titled “4. Nested Paths”When the source sits one level in, use a path. A path is a chain of segments, and each segment subscribes to its own owner. Replacing an intermediate object reconnects everything downstream.
A path does not care which source kind it walks. ObservableValue, MewProperty and INotifyPropertyChanged members can appear in the same chain.
4.1 One dotted line
Section titled “4.1 One dotted line”This is the recommended form. Dotted member access is split into a segment chain at compile time.
new Label().Bind(Label.TextProperty, vm, x => x.CurrentUser.Profile.DisplayName);Each step picks how to observe from the member’s type: PropertyChanged for INotifyPropertyChanged, the wrapper’s notification for ObservableValue<T>, the matching {Name}Property for a MewObject, and a non-observing segment when none of those apply.
Six syntax forms are accepted.
| Form | Example |
|---|---|
| Member access | x.A.B |
| Null-conditional | x.A?.B |
| Cast | ((User)x.Current).Name |
as cast |
(x.Current as User).Name |
| Null-forgiving | x.A!.B |
| Constant indexer | x.Items[0].Name |
Computed expressions, method calls and conditional operators are not paths and produce a compile error. Move computation into convert. Indexer arguments must be constants, because the generated path is a static field and cannot hold a local from the call site.
This form requires .NET 9 SDK or newer to build. Below Roslyn 4.12 the source generator cannot load, multi-step access becomes a compile error, and you use the explicit chain in 4.2 instead. Only the syntax is lost, not the capability. The target framework you build for does not matter, only the SDK you build with.
4.2 Explicit chain
Section titled “4.2 Explicit chain”Use this to keep a path in a static field shared by several elements, or to support builds where the generator does not run. A BindingPath is immutable and holds no root instance until it is attached.
static readonly BindingPath<AppViewModel, string> DisplayNamePath = BindingPath .From<AppViewModel>() .ThenNotifying(x => x.CurrentUser!) .ThenNotifying(x => x.DisplayName);
new Label().Bind(Label.TextProperty, vm, DisplayNamePath, fallbackValue: "-");Add ! to a nullable intermediate so the next segment’s owner type is non-nullable. The operator does not disable the runtime null checks.
4.3 Segment kinds
Section titled “4.3 Segment kinds”| How it is appended | Owner | Observes changes | TwoWay leaf |
|---|---|---|---|
Then(getter) |
anything | No | No |
Then(selector) |
an owner exposing ObservableValue<T> |
Yes | Yes |
Then(property) |
MewObject |
Yes | Unless the property is read-only |
ThenNotifying(getter, setter?) |
INotifyPropertyChanged |
Yes | When a setter is supplied |
ThenIndexed(getter) |
a notifying collection or indexer | Yes | No |
A non-observing Then(getter) is evaluated on the initial attach and whenever an upstream segment rebuilds the chain below it. A change in the getter result alone raises nothing, so the binding does not refresh. That is the right choice when the intermediate value never changes after construction.
4.4 Null and fallback
Section titled “4.4 Null and fallback”- A null intermediate makes the path unavailable and applies
fallbackValue. The getter overloads of 3.2 take one as well, right after the getter orconvert. - When an observed intermediate becomes non-null again, the path reconnects automatically.
- Null from the last segment is the real source value and is not replaced by the fallback.
- A selector that returns a null
ObservableValueis a broken path and throws.
The observer never calls a downstream selector with a null owner. C# cannot express that runtime guarantee in the generic signature, so nullable intermediate parameters use ! as in the example above.
4.5 TwoWay paths
Section titled “4.5 TwoWay paths”The last segment must be writable; see the last column in 4.3. A converted TwoWay path needs convertBack, and a path binding throws rather than degrading to OneWay in silence.
While a path is unavailable, target changes are not buffered. When it reconnects, the current source value overwrites the fallback or any temporary value.
4.6 Collections
Section titled “4.6 Collections”ObservableCollection<T> also implements INotifyPropertyChanged, so a collection’s own properties are observed.
new Label().Bind(Label.TextProperty, vm, x => x.Items.Count, count => $"{count} items");Indexers are observed too. When the owner implements INotifyCollectionChanged the segment subscribes to collection changes; when it only implements INotifyPropertyChanged it subscribes to the conventional Item[] indexer notification.
// Updates when the element at index 0 is replaced or an item is inserted before itnew Label().Bind(Label.TextProperty, vm, x => x.Items[0].Name);
// Explicit chainBindingPath.From<AppViewModel>() .ThenNotifying(x => x.Items) .ThenIndexed(x => x[0]);In the dotted form the declared static type decides. A property declared as IReadOnlyList<T> does not become an observing segment even when the instance is an ObservableCollection<T>. Calling ThenIndexed directly checks the instance instead, so it has no such limit.
An index that no longer exists makes the path unavailable and applies fallbackValue. When the indexer is the last segment, rule 4.4 applies and null is delivered as the real value.
For list UI itself, use ItemsSource. List controls observe additions and removals on their own. An indexer in a path is for watching one item at a fixed position.
4.7 Diagnostics
Section titled “4.7 Diagnostics”| ID | Severity | Meaning |
|---|---|---|
| MEW1201 | Warning | A non-observing Then whose owner implements INotifyPropertyChanged. Offers a fix to ThenNotifying |
| MEW1202 | Error | A ThenNotifying getter that is not a single member access |
| MEW1203 | Error | A dotted multi-step getter in a build where the generator does not run |
| MEWG001 | Error | A getter that cannot be split into path segments |
5. Combining Several Sources
Section titled “5. Combining Several Sources”A displayed value that depends on more than one source cannot be expressed as a path, because a path is a chain with one subscription per step. Bind therefore also takes two to four inputs and a combine function, and recomputes the value whenever any input changes.
When every input is a notifying property of the same view model, pass the getters after the source and the combine function last.
new TextBlock().Bind(TextBlock.TextProperty, vm, x => x.FirstName, x => x.LastName, (first, last) => $"{first} {last}");When the inputs come from different objects or from different kinds of source, wrap each one in BindingInput.From.
new TextBlock().Bind(TextBlock.TextProperty, BindingInput.From(order, x => x.Customer.Name), BindingInput.From(quantitySlider, RangeBase.ValueProperty), BindingInput.From(unitPrice), (customer, count, price) => $"{customer}: {count * price:0.00}");| Input | Source |
|---|---|
BindingInput.From(vm, x => x.Name) |
An INotifyPropertyChanged property (2.2). A dotted getter follows 4.1 |
BindingInput.From(root, path) |
A BindingPath (4.2) |
BindingInput.From(observable) |
An ObservableValue<T> (2.1) |
BindingInput.From(element, RangeBase.ValueProperty) |
Another element’s property (2.3) |
- The binding is always one-way, also on a target that is two-way by default such as
TextBox.Text. What the user types stays on the target until an input changes. - The combine function runs only while every input is available. While a null intermediate breaks an input’s path, the target shows the property type’s default value, or
fallbackValuewhen you pass one right before the combine function. Anullthat an input actually holds reaches the combine function as a value. - When an input cannot be read or the combine function throws, the target keeps its last value and the binding reports the error. The next change tries again.
- An input from
BindingInput.Fromcan be used in several bindings. Each binding observes the source on its own, andClearBinding, disposing the target, andTemplateContext.Resetrelease it like any other binding.
new TextBlock().Bind(TextBlock.TextProperty, vm, x => x.Customer.Name, x => x.Total, "-", // fallbackValue (name, total) => $"{name}: {total}");When the view model can own the combined value, letting it compute and notify (a FullName property, for example) is still simpler, because the view then watches one thing.
A computation over a single source does not need any of this. Use convert from 3.3.
6. Lifetime and Memory
Section titled “6. Lifetime and Memory”Every observing segment uses a weak subscription, so a long-lived source never keeps a target alive. The reverse does not hold: a target owns its active bindings and therefore keeps the root and the current path objects alive until ClearBinding, target disposal, or TemplateContext.Reset.
Bindings are released automatically when the control is disposed.
var textBox = new TextBox().BindText(vm.Name); // released when the window closesClearBinding removes the binding and the value it supplied, revealing the next lower value source. Note that no value is left behind.
Subscriptions you make directly on an ObservableValue are yours to release.
counter.Subscribe(OnChanged);counter.Unsubscribe(OnChanged);static on the lambdas you pass to a path is recommended, not required. A path stores its delegates, so a captured object lives as long as the path or any binding using it.
7. Methods by Control
Section titled “7. Methods by Control”| Method | Direction | Description |
|---|---|---|
BindText(ObservableValue<string>) |
One-way | Text |
BindText<T>(ObservableValue<T>, Func<T, string>) |
One-way | Converted |
TextBox / MultiLineTextBox
Section titled “TextBox / MultiLineTextBox”| Method | Direction | Description |
|---|---|---|
BindText(ObservableValue<string>) |
Two-way | Text input |
Button
Section titled “Button”| Method | Direction | Description |
|---|---|---|
BindContent(ObservableValue<string>) |
One-way | Button text |
BindContent<T>(ObservableValue<T>, Func<T, string>) |
One-way | Converted |
CheckBox / RadioButton / ToggleSwitch
Section titled “CheckBox / RadioButton / ToggleSwitch”| Method | Direction | Description |
|---|---|---|
BindIsChecked(ObservableValue<bool>) |
Two-way | Checked state |
ListBox / ComboBox
Section titled “ListBox / ComboBox”| Method | Direction | Description |
|---|---|---|
BindSelectedIndex(ObservableValue<int>) |
Two-way | Selected index |
Slider / ProgressBar
Section titled “Slider / ProgressBar”| Method | Direction | Description |
|---|---|---|
BindValue(ObservableValue<double>) |
Two-way on Slider, one-way on ProgressBar | Value |
UIElement (common)
Section titled “UIElement (common)”| Method | Direction | Description |
|---|---|---|
BindIsVisible(ObservableValue<bool>) |
One-way | Visibility |
BindIsEnabled(ObservableValue<bool>) |
One-way | Enabled state |
Any MewProperty
Section titled “Any MewProperty”| Method | Direction | Description |
|---|---|---|
Bind(MewProperty<T>, ObservableValue<T>) |
Default | Direct |
Bind(MewProperty<TProp>, ObservableValue<TSource>, convert, convertBack?) |
Default | Converted |
Bind(MewProperty<T>, TSource, getter, setter?) |
Target default | INotifyPropertyChanged source (2.2); setter optional |
Bind(MewProperty<TProp>, TSource, getter, convert, setter?, convertBack?) |
Two-way with convertBack | Converted INotifyPropertyChanged source |
Bind(MewProperty<T>, TSource, Func<TSource, ObservableValue<T>>) |
Default | ObservableValue reached through an owner |
Bind(MewProperty<T>, MewObject, MewProperty<T>) |
Default | Another element’s property (2.3) |
Bind(MewProperty<T>, TRoot, BindingPath<TRoot, T>, mode?, fallbackValue?) |
Default | Path (section 4) |
Bind(MewProperty<T>, TSource, getter, fallbackValue, setter?) |
Target default | INotifyPropertyChanged source with a fallback (4.4) |
Bind(MewProperty<TProp>, TSource, getter, convert, fallbackValue, setter?, convertBack?) |
Two-way with convertBack | Converted, with a fallback (4.4) |
Bind(MewProperty<TProp>, TSource, getter1, getter2, fallbackValue?, combine) |
One-way | Two to four properties of one source (section 5) |
Bind(MewProperty<TProp>, BindingInput<T1>, BindingInput<T2>, fallbackValue?, combine) |
One-way | Two to four inputs (section 5) |
SetBinding offers the same set; Bind is the fluent wrapper over it.
8. Best Practices
Section titled “8. Best Practices”Use a source that raises notifications
Section titled “Use a source that raises notifications”// Good: ObservableValueclass ViewModel { public ObservableValue<string> Name { get; } = new(""); }
// Good: INotifyPropertyChangedclass ViewModel : INotifyPropertyChanged { public string Name { get; set; } }
// Bad: nothing notifies, so the binding never updatesclass ViewModel { public string Name { get; set; } }Keep display logic in the UI layer
Section titled “Keep display logic in the UI layer”// Good: convert at the bindingnew Label().BindText(vm.Price, p => $"${p:N0}");
// Bad: formatting in the view modelclass ViewModel { public ObservableValue<string> FormattedPrice { get; } }Validate with coerce
Section titled “Validate with coerce”var age = new ObservableValue<int>(0, v => Math.Clamp(v, 0, 150));Dotted paths for one use, explicit chains for sharing
Section titled “Dotted paths for one use, explicit chains for sharing”// Used in one placelabel.Bind(Label.TextProperty, vm, x => x.CurrentUser.Profile.DisplayName);
// Shared by several elementsstatic readonly BindingPath<AppViewModel, string> DisplayName = /* section 4.2 */;