Event Handling in Blazor

Analogy categoryAnalogies

Wiring DOM Events to C# Methods

Blazor exposes DOM events as Razor attributes prefixed with @, such as @onclick, @onkeydown, or @onmouseover, letting you attach a C# method directly to a UI event without writing any JavaScript; the framework automatically wires up the underlying addEventListener call through its interop layer and routes the event back into the component's render pipeline, triggering a re-render after the handler completes.

🏏

Cricket analogy: An lbw appeal from the bowler is a direct signal routed straight to the umpire's decision system, just as @onclick routes a browser click event directly to your C# handler without needing custom JavaScript plumbing.

Event Argument Types and Handler Signatures

Handlers can accept the specific EventArgs subtype matching the event — MouseEventArgs for @onclick, KeyboardEventArgs for @onkeydown, ChangeEventArgs for @onchange — giving typed access to details like e.CtrlKey, e.Key, or e.Value; a handler can also take no parameters at all if the extra data isn't needed, and Blazor infers the correct delegate signature automatically at compile time.

🏏

Cricket analogy: A third umpire reviewing a run-out gets a specific data packet with stump-camera angle and timing, tailored to that exact type of review, just as a KeyboardEventArgs handler gets keyboard-specific data like e.Key.

Async Handlers and Preventing Default Behavior

Event handlers can be async Task methods, and Blazor automatically awaits them and triggers a re-render once the task completes, which is essential for handlers that call an HTTP service via HttpClient before updating the UI; to prevent a browser's default action, such as a form auto-submitting or a link navigating, use the @onclick:preventDefault or @onsubmit:preventDefault modifier rather than relying on JavaScript's event.preventDefault().

🏏

Cricket analogy: A DRS review pauses live play and waits for the third umpire's full analysis before resuming the match, just as an async event handler pauses the UI update until the awaited HTTP call completes.

razor

<form @onsubmit:preventDefault @onsubmit="HandleSearchAsync">
    <input @bind="query" @bind:event="oninput" />
    <button type="submit" disabled="@isLoading">Search</button>
</form>

@if (isLoading)
{
    <p>Loading...</p>
}

@code {
    private string query = string.Empty;
    private bool isLoading;
    private List<string> results = new();

    private async Task HandleSearchAsync()
    {
        isLoading = true;
        results = await Http.GetFromJsonAsync<List<string>>($"api/search?q={query}") ?? new();
        isLoading = false;
    }
}

You can combine an EventCallback<T> parameter (used for parent-child notification, see Component Parameters) with the same @onclick-style syntax when a child component exposes its own custom event, e.g. <StarRating OnRated="HandleRated" />, keeping the calling convention consistent across native DOM events and custom component events.

Always declare async event handlers as async Task, never async void. An async void handler's exceptions can't be awaited or caught by Blazor's error handling, and the framework won't know when the operation completes, so it can't reliably schedule the follow-up re-render.

@onclick, @onkeydown, @oninput and similar @-prefixed attributes wire DOM events to C# methods with no JavaScript required.
Blazor infers the correct EventArgs subtype (MouseEventArgs, KeyboardEventArgs, ChangeEventArgs) from the handler's signature.
A handler can omit the EventArgs parameter entirely if the event data isn't needed.
Event handlers can be async Task methods; Blazor awaits them and re-renders once they complete.
Use @onclick:preventDefault or @onsubmit:preventDefault to stop default browser behavior, not JS's preventDefault().
Always use async Task rather than async void for handlers so exceptions and completion are properly tracked.