Directives in Blazor WebAssembly

Directives are features that add additional behaviour to a Razor Component in your Blazor WebAssembly website. With Blazor's built-in directives, you can manage many aspects of the user interactions. There are 3 types of directives in Blazor WebAssembly:

  1. Compiling.
  2. DOM interaction.
  3. Utilities.
You can download the example code used in this topic on GitHub.

Compiling directives

Compiling directives are directives that manipulate how a Razor Component is compiled. The following directives belong to the compiling group:

Directive identifier Description Type
@inherits Specify the base class for a component Compiling
@namespace Specify the namespace for a component Compiling
@implements Specify the interface for a component Compiling
@preservewhitespace Remove all redundant white spaces from an element Compiling
@typeparam Specify a generic class for a component Compiling
@layout Specify the layout for a component Compiling

An example of compiling directives group is @implements. Assuming you have the following code:

@implements IDisposable

...

@code {
    public void Dispose()
    {
    }
}

When you remove the Dispose method, Visual Studio 2022 will emit an error when you are building the project as follows:

compiling-group-error.png


DOM interaction directives

DOM interaction directives are directives that are used to interact with the DOM. The following directives belong to the DOM interaction group:

Directive identifier Description Type
@attributes Attach a dictionary of attributes to the element DOM interaction
@on<event> Attach the event handlers to the element's event DOM interaction
@bind-<attribute>:<event> Create a 2-ways binding to an element attribute DOM interaction
@key Set a unique identifier for an element DOM interaction
@ref Refer the element to an C# instance DOM interaction
@code Add C# code that defines the component's logic, state, and behavior DOM interaction

We will use @attributes to demonstrates the DOM interaction group. Assuming you have the following code:

<div @attributes="Attributes">Inspect me to see my attributes.</div>

@code {
    Dictionary<string, object> Attributes { get; set; } = new()
    {
        { "example-string", "Blazor School" },
        { "example-int", 10 },
        { "example-object", new 
            { 
                date = DateTime.Now 
            } 
        }
    };
}

With the above code, Blazor WebAssembly will render the following HTML tag:

<div example-string="Blazor School" example-int="10" example-object="{ date = 2/21/2022 8:34:57 PM }">Inspect me to see my attributes.</div>

Blazor event and HTML event

When interact with the DOM, you will have to handle events of an element. Blazor event and HTML shared the same name, however they are different. The following image illustrates the different between Blazor event and HTML event:

blazor-vs-html-event.png

A sample button with HTML event:

<button class="btn btn-primary" type="button" onclick="alert('HTML event fired!')">HTML Event</button>

A sample button with Blazor event:

<button class="btn btn-primary" type="button" @onclick='_ => ExampleString = "Hello Blazor School!"'>Blazor Event</button>

@code {
    public string ExampleString { get; set; } = "";
}
This tutorial will only focus on Blazor event.

Handle HTML event with Blazor

Each HTML event has it own data. You can also pass this event data to C# method for further processing. Follow the following steps to pass HTML event data to C# method.

  1. Create a C# method with equivalent C# event. For example:
public void UpdateCoordinate(MouseEventArgs args)
{
    Coordinate = $"X: {args.ClientX} Y: {args.ClientY}";
}
  1. Pass HTML event data. For example:
<div @onmousemove="UpdateCoordinate"></div>

The following table is the HTML event equivalent C# event.

HTML Event C# Event Event Group
onfocus FocusEventArgs Focus
onblur FocusEventArgs Focus
onfocusin FocusEventArgs Focus
onfocusout FocusEventArgs Focus
onmouseover MouseEventArgs Mouse
onmouseout MouseEventArgs Mouse
onmousemove MouseEventArgs Mouse
onmousedown MouseEventArgs Mouse
onmouseup MouseEventArgs Mouse
onclick MouseEventArgs Mouse
ondblclick MouseEventArgs Mouse
onwheel WheelEventArgs Mouse
onmousewheel WheelEventArgs Mouse
oncontextmenu MouseEventArgs Mouse
ondrag DragEventArgs Drag
ondragend DragEventArgs Drag
ondragenter DragEventArgs Drag
ondragleave DragEventArgs Drag
ondragover DragEventArgs Drag
ondragstart DragEventArgs Drag
ondrop DragEventArgs Drag
onkeydown KeyboardEventArgs Keyboard
onkeyup KeyboardEventArgs Keyboard
onkeypress KeyboardEventArgs Keyboard
onchange ChangeEventArgs Input
oninput ChangeEventArgs Input
oninvalid EventArgs Input
onreset EventArgs Input
onselect EventArgs Input
onselectstart EventArgs Input
onselectionchange EventArgs Input
onsubmit EventArgs Input
onbeforecopy EventArgs Clipboard
onbeforecut EventArgs Clipboard
onbeforepaste EventArgs Clipboard
oncopy ClipboardEventArgs Clipboard
oncut ClipboardEventArgs Clipboard
onpaste ClipboardEventArgs Clipboard
ontouchcancel TouchEventArgs Touch
ontouchend TouchEventArgs Touch
ontouchmove TouchEventArgs Touch
ontouchstart TouchEventArgs Touch
ontouchenter TouchEventArgs Touch
ontouchleave TouchEventArgs Touch
ongotpointercapture PointerEventArgs Pointer
onlostpointercapture PointerEventArgs Pointer
onpointercancel PointerEventArgs Pointer
onpointerdown PointerEventArgs Pointer
onpointerenter PointerEventArgs Pointer
onpointerleave PointerEventArgs Pointer
onpointermove PointerEventArgs Pointer
onpointerout PointerEventArgs Pointer
onpointerover PointerEventArgs Pointer
onpointerup PointerEventArgs Pointer
oncanplay EventArgs Media
oncanplaythrough EventArgs Media
oncuechange EventArgs Media
ondurationchange EventArgs Media
onemptied EventArgs Media
onpause EventArgs Media
onplay EventArgs Media
onplaying EventArgs Media
onratechange EventArgs Media
onseeked EventArgs Media
onseeking EventArgs Media
onstalled EventArgs Media
onstop EventArgs Media
onsuspend EventArgs Media
ontimeupdate EventArgs Media
onvolumechange EventArgs Media
onwaiting EventArgs Media
onloadstart ProgressEventArgs Progress
ontimeout ProgressEventArgs Progress
onabort ProgressEventArgs Progress
onload ProgressEventArgs Progress
onloadend ProgressEventArgs Progress
onprogress ProgressEventArgs Progress
onerror ErrorEventArgs Progress
onactivate EventArgs Other
onbeforeactivate EventArgs Other
onbeforedeactivate EventArgs Other
ondeactivate EventArgs Other
onended EventArgs Other
onfullscreenchange EventArgs Other
onfullscreenerror EventArgs Other
onloadeddata EventArgs Other
onloadedmetadata EventArgs Other
onpointerlockchange EventArgs Other
onpointerlockerror EventArgs Other
onreadystatechange EventArgs Other
onscroll EventArgs Other
ontoggle EventArgs Other

Pass parameters to C# method

Sometimes, you want to pass parameters to your C# method from the DOM. You can pass a parameter to a C# method from the DOM as follows:

<button type="button" @onclick="_ => ExampleMethodWithoutHtmlEvent(ExampleString)">Example parameterized method without HTML event</button>

@code {
    public string ExampleString { get; set; } = "";

    public void ExampleMethodWithoutHtmlEvent(string exampleString)
    {
    }
}

In case you want to pass HTML event data along with other parameters, you can do as follows:

<button type="button" @onclick="(e) => ExampleMethodWithHtmlEvent(e, ExampleString)">Example parameterized method with HTML event</button>

@code {
    public string ExampleString { get; set; } = "";
    
    public void ExampleMethodWithHtmlEvent(MouseEventArgs eventArgs, string exampleString)
    {
    }
}

preventDefault in Blazor WebAssembly

Each event has it own default browser actions. preventDefault is a JavaScript method that cancels the default actions of the current event. For example, a checkbox will be ticked when you click in the checkbox. When you prevent default browser actions, the checkbox will not be ticked. The following video will demonstrate preventDefault:

Blazor supports you to use preventDefault method without including JavaScript code. Simply just add @<Blazor_event>:preventDefault. For example:

<input type="checkbox" @onclick:preventDefault />

stopPropagation in Blazor WebAssembly

An HTML tag can be nested in another tag. When an event in a child tag fire, the event will propagate to the upper level. The following image illustrates the propagation of HTML event:

propagation.png

To prevent an event being propagated to the upper level, you can use stopPropagation JavaScript method. The following video demonstrates the stopPropagation:

Blazor supports you to use stopPropagation method without including JavaScript code. Simply just add @<Blazor_event>:stopPropagation. For example:

<div @onclick:stopPropagation></div>

Utilities directives

Utilities directives are directives that add various features to your component. The following directives belong to the utilities group:

Directive identifier Description Type
@<C#-keyword>, @{<C# Code>},@(<C# Code>) Inject C# code to HTML template Utilities
@inject Inject an instance into a component Utilities
@page Specify the route and parameter to a component Utilities
@section Define a section, not available for Razor Component. Not commonly used in Blazor. N/A
@functions Deprecated, use @code instead N/A

An example of utilities directives is @page. Assuming you have the following code:

@page "/utility"

<div>The <code>@@page</code> directive helps you to navigate to this page.</div>

The above example uses the @page directive to specify the route for the current component so that you can access the component by using localhost:XXXX/utility.

BLAZOR SCHOOL
Designed and built with care by our dedicated team, with contributions from a supportive community. We strive to provide the best learning experience for our users.
Docs licensed CC-BY-SA-4.0
Copyright © 2021-2025 Blazor School
An unhandled error has occurred. Reload 🗙