Directives in Blazor Server

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

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:

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:

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:

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 Server 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:

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}";
}

2. Pass HTML event data. For example:

<div @onmousemove="UpdateCoordinate"></div>

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

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 Server

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 Server

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:

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:

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.