skip to content

In Blazor, what must a custom component declare so a parent can use @bind-Value on it, and how do @bind-Value:after and :get/:set change that?

level: middleimportance: should knowfreq 50%

answer

  1. Value plus ValueChanged
  2. the {Name}Changed naming convention
  3. ValueChanged.InvokeAsync, not assigning Value
  4. ValueExpression for forms
  5. :after runs once the value is assigned

basics

~20 s

The component needs a [Parameter] Value and a matching [Parameter] EventCallback<T> ValueChanged; @bind-Value then expands to both. The child reports a new value by invoking ValueChanged, never by assigning Value; :after adds a follow-up step and :get/:set take over the assignment.

solid answer

~40 s

`@bind-Value="selectedStatus"` is compiled into two attributes: `Value="selectedStatus"` and `ValueChanged` set to a callback that assigns the new value to `selectedStatus`. So the child must declare `[Parameter] public T Value { get; set; }` and `[Parameter] public EventCallback<T> ValueChanged { get; set; }` - the `{Parameter}Changed` name and a matching type are what make a parameter bindable; the same convention gives `@bind-Year` for a `Year`/`YearChanged` pair. Inside, the child calls `await ValueChanged.InvokeAsync(newValue)` and lets the parent's re-render send the value back, rather than writing `Value`. A component used in an `EditForm` can also declare `Expression<Func<T>> ValueExpression`, which the framework assigns to identify the bound field. `@bind-Value:after="Reload"` runs a method after the value is assigned; `@bind-Value:get` / `@bind-Value:set` replace the generated assignment with your own setter, always used as a pair.

code

razor · 15 lines
razor
@* StatusPicker.razor *@
<select value="@Value" @onchange="OnChange">
    @foreach (var s in Enum.GetValues<WorkOrderStatus>())
    {
        <option value="@s">@s</option>
    }
</select>

@code {
    [Parameter] public WorkOrderStatus Value { get; set; }
    [Parameter] public EventCallback<WorkOrderStatus> ValueChanged { get; set; }

    private Task OnChange(ChangeEventArgs e)
        => ValueChanged.InvokeAsync(Enum.Parse<WorkOrderStatus>(e.Value!.ToString()!));
}

go deeper

for a junior

Remember the Value and ValueChanged pair and that @bind-Value is shorthand for setting both.

for a middle

Explain what the compiler generates, the naming convention, why the child invokes ValueChanged instead of assigning Value, and what :after and :get/:set do.

for a senior

Build bindable wrapper components that pass bindings through several levels with :get/:set, and add ValueExpression when they must join EditForm validation.

for a principal

Define the binding contract for a shared component library so every input-like component supports @bind-Value consistently and has a single owner for each value.

## What @bind-Value means on a component On an HTML element, `@bind` binds to the element's value and a DOM event. On a **component**, `@bind-{Parameter}` binds to a component parameter, and it is pure compile-time sugar. For a fleet app's `StatusPicker`: - `<StatusPicker @bind-Value="filter.Status" />` becomes - `<StatusPicker Value="filter.Status" ValueChanged="(v) => filter.Status = v" />` (conceptually; the compiler builds an `EventCallback` for the parent). The Razor compiler finds the pair by **naming convention**: a parameter `X` and an `EventCallback<T>` parameter named `XChanged` whose `T` matches `X`'s type. That is why `@bind-Value` needs `Value` + `ValueChanged`, and why a component with `Year` + `YearChanged` supports `@bind-Year`. ## Writing the child correctly 1. Declare `[Parameter] public WorkOrderStatus Value { get; set; }`. 2. Declare `[Parameter] public EventCallback<WorkOrderStatus> ValueChanged { get; set; }`. 3. When the user picks a status, call `await ValueChanged.InvokeAsync(newStatus)`. 4. Do **not** assign `Value = newStatus` and hope it sticks: the parent owns the value, and its re-render (triggered by the `EventCallback`) sends the updated value back down. Assigning `Value` locally leaves the parent's field unchanged, so parent and child disagree, and the local value is lost whenever the parent next re-applies parameters. Because `ValueChanged` is an `EventCallback`, the parent re-renders automatically after the assignment, so other parts of the page that read `filter.Status` update too. ## ValueExpression and forms Blazor's own input components (`InputText`, `InputSelect<TValue>` and the rest of `InputBase<TValue>`) declare a third parameter, `Expression<Func<TValue>>? ValueExpression`. When you write `@bind-Value`, the framework assigns it an expression that identifies the bound property, which the form uses to build a `FieldIdentifier` for validation messages. A custom component that should take part in `EditForm` validation declares `ValueExpression` the same way; outside a form it is not needed. How the validation then works belongs to the forms topic. ## Modifiers: :after, :get and :set | Syntax | What it does | |---|---| | `@bind-Value="x"` | sets `Value`, and assigns `x` when `ValueChanged` fires | | `@bind-Value="x" @bind-Value:after="ReloadAsync"` | as above, then runs `ReloadAsync` (sync or `Task`-returning) after `x` has been assigned | | `@bind-Value:get="x" @bind-Value:set="SetStatusAsync"` | reads `x` for `Value`; when the child raises `ValueChanged`, calls your setter instead of assigning `x` directly | | `Value="x" ValueChanged="OnChanged"` | the manual form, useful when you need full control | Rules worth remembering: - `:get` and `:set` are always used **together**. - `:after` accepts a method returning `void` or `Task`; the docs state that passing an `EventCallback` to `@bind:after` is not supported. - `:get`/`:set` is the modern replacement for the old trick of binding to a C# property whose setter discarded the `Task` from `EventCallback.InvokeAsync`. ## Chaining through several components A `WorkOrderFilters` component that wraps `StatusPicker` and itself exposes `Status` / `StatusChanged` passes the binding through with `@bind-Value:get="Status" @bind-Value:set="StatusChanged"` - reading its own parameter and forwarding changes to its own callback, without ever assigning its own parameter. That keeps a single owner, the page, at the top of the chain.

  • Why does @bind-Status fail to compile on a component whose callback is named OnStatusChanged?
    Binding relies on the `{Parameter}Changed` convention: for `@bind-Status` the compiler looks for an `EventCallback<T>` parameter named exactly `StatusChanged` whose type matches `Status`. `OnStatusChanged` does not match the pattern, so the compiler cannot generate the setter half of the binding. Rename it or wire `Status` and the callback manually.
  • When would you use :get/:set instead of :after?
    Use `:after` when the value should simply be assigned and something must happen afterwards, such as reloading data. Use `:get`/`:set` when you need to intercept the assignment itself - to validate, transform or reject the value, or to forward it to another callback when you are passing a binding through an intermediate component that must not assign its own parameter.

  • @bind-Value works on any component that has a public Value property, with no callback needed.
  • The child should set Value itself and then call StateHasChanged so the parent sees it.
  • The change callback can have any name as long as its type is EventCallback<T>.
  • @bind-Value:get can be used alone to make a binding read-only.
  • @bind-Value:after must be given an EventCallback so the parent re-renders.