Difference between @bind and @bind-value
Short Version
@bind
is an override of @bind-value
with the event set to "onchange".
These two commands are equivalent:
... @bind-value="userName" @bind-value:event="onchange" ...
... @bind="userName" ...
Long Version
The @bind
attribute accomplishes two separate (but related) tasks:
- Binds an expression to the value of the
<Input...
component - Binds a delegate that will trigger the component's
ValueChanged
property
Both the expression and the delegate are required. An implementation of @bind-Value
looks like this:
... @bind-value="userName" @bind-value:event="onchange" ...
We are setting both the expression (="userName"
) and the delegate (="onchange"
).
The "easier" @bind=
is just an override with the delegate preset to "onchange". So these two commands are functionally the same:
... @bind-value="userName" @bind-value:event="onchange" ...
... @bind="userName" ...
A greatly simplified analogy using overriding methods:
public void bind-value(string value, string event)
{..}
public void bind(string value)
{
bind-value(value, "onchange");
}
A couple of common use-cases for using the full @bind-value
version are
- updating the UI as the user types
- validating an email address as the user types
Remember, the onchange
event will only trigger PropertyChanged
when the component loses focus. Instead, we want PropertyChanged
to be triggered by the oninput
event:
... @bind-value="H1Content" @bind-value:event="oninput" ...
... @bind-value="email" @bind-value:event="oninput" ...
There is not any significant deference between these two. The you can use @bind-value and @bind-value:event or you can use @bind and @bind:event pairs arbitrary.
EDITED because @dragon-warrior and @somedotnetguy coments.
ASP.NET >= Core 3.1
@bind-value:event
is not more required for events. Just use @bind:event
.
ASP.NET Core 3.0
Quoting ASP.NET Core 3.0 Component Binding (currently unavailable) docs:
Data binding to both components and DOM elements is accomplished with the
@bind
attribute. (...) Using@bind
with aCurrentValue
property (<input @bind="CurrentValue" />
) is essentially equivalent to the following:
<input value="@CurrentValue"
@onchange="@((ChangeEventArgs __e) => CurrentValue = __e.Value)" />
In addition to handling onchange events with
@bind
syntax, a property or field can be bound using other events by specifying an@bind-value
attribute with an event parameter (@bind-value:event
). (onchange
,oninput
)
Summarizing
If you want to reset binded value on each input change (instead to set all changes at once on lost input focus) you should to use @bind-value
and oninput
on @bind-value:event
:
<input @bind-value="CurrentValue"
@bind-value:event="oninput" />
If you try to use @bind-value:event
without @bind-value
(using just @bind
) a pre-compiling error is raised:
error RZ10004: Could not find the non-parameterized bind attribute that corresponds to the attribute 'bind-value:event'
But the XXX.razor.g.cs
generated file is the same for @bind
and @bind-value
.