Skip to content

Clarify TwoWay binding initialization direction in data binding documentation #3067

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

Clarify TwoWay binding initialization direction in data binding documentation #3067

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b0ea8a7
Initial plan
Copilot Oct 21, 2025
2d71fb8
Add clarification about TwoWay binding initialization direction
Copilot Oct 21, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions docs/fundamentals/data-binding/binding-mode.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,15 +36,15 @@ In this example, the <xref:Microsoft.Maui.Controls.Label> is the data-binding so

:::image type="content" source="media/binding-mode/reversebinding.png" alt-text="Reverse binding.":::

In addition, the <xref:Microsoft.Maui.Controls.Slider> continues to work. This is because the default binding mode for the `Value` property of <xref:Microsoft.Maui.Controls.Slider> is `TwoWay`. This means that when the `Value` property is a data-binding target, then the target is set from the source but the source is also set from the target. This allows the <xref:Microsoft.Maui.Controls.Slider> to be set from the initial `Opacity` value.
In addition, the <xref:Microsoft.Maui.Controls.Slider> continues to work. This is because the default binding mode for the `Value` property of <xref:Microsoft.Maui.Controls.Slider> is `TwoWay`. This means that when the `Value` property is a data-binding target, then the target is set from the source but the source is also set from the target. When a `TwoWay` binding is initialized, the target is set from the source first, which allows the <xref:Microsoft.Maui.Controls.Slider> to be set from the initial `Opacity` value.

> [!NOTE]
> Bindable properties don't signal a property change unless the property actually changes. This prevents an infinite loop.

If the default binding mode on the target property is not suitable for a particular data binding, it's possible to override it by setting the `Mode` property of `Binding` (or the `Mode` property of the `Binding` markup extension) to one of the members of the `BindingMode` enumeration:

- `Default`
- `TwoWay` — data goes both ways between source and target
- `TwoWay` — data goes both ways between source and target. When initialized, the target is set from the source first.
- `OneWay` — data goes from source to target
- `OneWayToSource` — data goes from target to source
- `OneTime` — data goes from source to target, but only when the `BindingContext` changes
Expand All @@ -63,7 +63,7 @@ Most bindable properties have a default binding mode of `OneWay` but some proper
- `On` property of <xref:Microsoft.Maui.Controls.SwitchCell>
- `Time` property of <xref:Microsoft.Maui.Controls.TimePicker>

These properties are defined as `TwoWay` because when data bindings are used with the Model-View-ViewModel (MVVM) pattern, the viewmodel class is the data-binding source, and the view, which consists of views such as <xref:Microsoft.Maui.Controls.Slider>, are data-binding targets. MVVM bindings resemble the example above, because it's likely that you want each view on the page to be initialized with the value of the corresponding property in the viewmodel, but changes in the view should also affect the viewmodel property.
These properties are defined as `TwoWay` because when data bindings are used with the Model-View-ViewModel (MVVM) pattern, the viewmodel class is the data-binding source, and the view, which consists of views such as <xref:Microsoft.Maui.Controls.Slider>, are data-binding targets. MVVM bindings resemble the example above, because it's likely that you want each view on the page to be initialized with the value of the corresponding property in the viewmodel, but changes in the view should also affect the viewmodel property. When initialized, a `TwoWay` binding sets the target from the source first, and then subsequent changes flow in both directions.

## One-way-to-source bindings

Expand Down