Directives

✅ Similar to Blazor Server

In Blazor, directives are powerful features that enable you to add additional behavior to a Razor Component on your website. With Blazor's built-in directives, you can manage various aspects of user interactions. These directives can be grouped into three types:

• Compiling.
• DOM interaction.
• Utilities.

You can download the example code used in this topic on GitHub.

Compiling directives

Blazor provides compiling directives that manipulate how a Razor Component is compiled. These directives include:

For instance, the @implements directive specifies the interface for a component, as shown in the example code where the Dispose method is implemented.

@implements IDisposable

...

@code {
    public void Dispose()
    {
    }
}

If the Dispose method is removed, Visual Studio 2022 will emit an error during project building.

DOM interaction directives

Blazor also provides DOM interaction directives used to interact with the DOM, such as

For example, the @attributes directive attaches a dictionary of attributes to an element, as demonstrated in the 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 
            } 
        }
    };
}

Blazor will render the HTML tag with the specified attributes:

<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 interacting with the DOM, you will need to handle events of an element. Although Blazor events and HTML events share the same name, they are different. The following image illustrates the difference between Blazor events and HTML events:

For example, a button with an HTML event is coded as follows:

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

On the other hand, a button with a Blazor event is coded as follows:

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

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

This tutorial will only focus on Blazor events.

Handle HTML event with Blazor

Handling HTML events with Blazor is a common task in web development. Each HTML event comes with its own data, and you can pass this event data to a C# method for further processing. Follow these steps to pass HTML event data to a C# method:

1. Create a C# method that corresponds to the relevant C# event, such as FocusEventArgs for the onblur event.

public void OnElementBlur(FocusEventArgs args)
{
}

2. Pass the HTML event data using the @on<event> syntax. For example, to pass focus event data to a OnElementBlur method:

<div @onblur="OnElementBlur"></div>

Here's a table of the HTML events and their corresponding C# events:

Pass parameters to a C# method from the DOM

To pass parameters to a C# method from the DOM, you can use the following syntax:

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

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

    public void ExampleMethodWithoutHtmlEvent(string exampleString)
    {
    }
}

If you need to pass HTML event data along with other parameters, you can modify the syntax 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

By default, events in Blazor trigger their respective browser actions. To cancel these actions, you can use the preventDefault() method in JavaScript. This method stops the default actions of the current event.

For instance, clicking on a checkbox will normally tick the checkbox. By using preventDefault(), the checkbox will not be ticked. You can see an example of preventDefault() in action in the following video:

Blazor makes it easy to use preventDefault() without writing any JavaScript code. Simply add @<Blazor_event>:preventDefault to your HTML element. For example:

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

stopPropagation in Blazor

HTML elements can be nested within each other, meaning that events that occur on a child element can propagate to its parent elements. This is known as event propagation, and it can be useful in some cases. However, there may be instances where you want to prevent an event from propagating to its parent elements. To achieve this, you can use the stopPropagation() method in JavaScript. In the following image, you can see an example of event propagation in HTML:

To prevent an event from propagating to its parent elements, you can use the stopPropagation() method. Here's a video that demonstrates how stopPropagation() works:

In Blazor, you can use the stopPropagation() method without writing any JavaScript code. Simply add @<Blazor_event>:stopPropagation to the HTML element where you want to stop event propagation. For example:

<div @onclick:stopPropagation></div>

Utilities directives

Utility directives are a set of directives that provide additional features to your components. The following directives are part of the utility group:

For example, the @page directive is a utility directive that specifies the route for a component. Here's an example that demonstrates how @page works:

@page "/utility"

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

In the example above, the @page directive sets the route for the current component to /utility. This means that you can access the component by navigating to localhost:XXXX/utility.