Creating Custom Tag Helpers in ASP.NET Core

Tag Helpers in ASP.NET Core are a powerful way to extend HTML in a clean and reusable way. They allow you to enrich your HTML markup with server-side logic while keeping your Razor views clean and easy to maintain. In this article, we’ll dive into how to create custom tag helpers from scratch, including a practical example.

What is a Tag Helper?

In simple terms, a Tag Helper enables server-side code to participate in creating and rendering HTML elements in Razor views. Unlike HTML helpers, Tag Helpers offer a more natural HTML syntax, making Razor pages easier to read and maintain. ASP.NET Core ships with built-in tag helpers like asp-for, asp-action, and asp-controller. However, you can create custom Tag Helpers to extend their functionality according to your needs.

Why Use Custom Tag Helpers?

Tag Helpers are especially useful when you want to:

• Reuse common UI components
• Separate concerns in your views
• Clean up complex Razor logic by moving it to the server side
• Reduce duplication in your HTML

Creating a Custom Tag Helper

Let’s create a custom Tag Helper that generates a Bootstrap-styled alert message box with a message type (info, success, warning, or danger) based on the input.

Step 1: Create a New ASP.NET Core Project

You can start by creating a new ASP.NET Core web application or use an existing one.

dotnet new mvc -n TagHelpersDemo

Step 2: Create a Custom Tag Helper Class

Create a new folder called TagHelpers in the root of your project. Inside this folder, add a new class file named AlertTagHelper.cs.

using Microsoft.AspNetCore.Razor.TagHelpers;
namespace TagHelpersDemo.TagHelpers
{
    [HtmlTargetElement("alert")]
    public class AlertTagHelper : TagHelper
    {
        public string Type { get; set; } = "info";
        public string Message { get; set; }
        public override void Process(TagHelperContext context, TagHelperOutput output)
        {
            // Set the tag name to "div" instead of "alert"
            output.TagName = "div";
          // Add Bootstrap alert classes
            output.Attributes.SetAttribute("class", $"alert alert-{Type}");
            
            // Set the inner content to the message
            output.Content.SetContent(Message);
        }
    }
}

Explanation:

• Inheritance: The AlertTagHelper class inherits from TagHelper. This is where we define the behavior and rendering logic for our custom tag.
• HtmlTargetElement: This attribute specifies which HTML tag the custom Tag Helper targets. In this case, it’s targeting an <alert> tag.
• Type Property: This property allows you to pass the type of alert (e.g., info, success, warning, or danger) from the view.
• Process Method: This method is where the actual rendering happens. We set the tag name to div (because there’s no native <alert> tag in HTML), add Bootstrap classes for styling, and set the content based on the Message property.

Step 3: Register the Tag Helper

To use the custom Tag Helper in your Razor views, you need to register it. Open your _ViewImports.cshtml file and add the following directive:

@addTagHelper *, TagHelpersDemo

This tells Razor to look for any Tag Helpers within the TagHelpersDemo namespace.

Step 4: Use the Tag Helper in a View

Now, you can use the alert tag in any of your Razor views. Open the Views/Home/Index.cshtml file and add the following markup:

@{
    ViewData["Title"] = "Home Page";
}<h1>Custom Tag Helper Example</h1>
<alert type="success" message="Your operation was successful!"></alert>
<alert type="warning" message="This is a warning message."></alert>
<alert type="danger" message="Something went wrong!"></alert>
<alert message="This is an informational message."></alert>

Here, we use our custom <alert> tag, passing the type and message attributes to generate Bootstrap-styled alert boxes.

Step 5: Run the Application

Run the application by executing the following command in your terminal:

dotnet run

Open your browser and navigate to the homepage. You should see the different alert boxes displayed with their respective message types.

Advanced Features: Child Content and Conditionals

Tag Helpers can be further extended with more advanced features like child content and conditional rendering. Here’s how you can enhance the AlertTagHelper to support both.

Adding Child Content

Instead of passing the message as an attribute, you can allow the developer to specify it as child content inside the alert tag.

Update the AlertTagHelper class to support child content:

public override async Task ProcessAsync(TagHelperContext context, TagHelperOutput output)
{
    output.TagName = "div";
    output.Attributes.SetAttribute("class", $"alert alert-{Type}");
    var childContent = await output.GetChildContentAsync();
    output.Content.SetHtmlContent(childContent.IsEmptyOrWhiteSpace ? Message : childContent.GetContent());
}

With this change, you can now use the Tag Helper as follows in your Razor view:

<alert type="success">Operation completed successfully!</alert>
<alert type="danger">
    <strong>Error!</strong> Something went wrong.
</alert>

Conclusion

Custom Tag Helpers in ASP.NET Core provide a flexible way to extend HTML elements, making your Razor views cleaner and more maintainable. By moving logic into reusable Tag Helpers, you can encapsulate functionality and styling in a way that’s both easy to use and test. In this article, we’ve seen how to create a basic Tag Helper to render Bootstrap-styled alerts, but the possibilities are endless. You can create custom components for forms, buttons, modals, and much more.

Next Steps

• Experiment with creating more complex Tag Helpers, such as those that accept child elements or manage more complex interactions with Razor pages.
• Look into using conditional logic within your Tag Helpers for even more dynamic rendering.