January 16, 2021

Using HTMX with ASP.NET Core: Introduction

Introduction

A few years ago I wrote a series of blog posts around the theme of “You might not need Angular”. The premise of that series was that we want to add tiny bits of interactivity to web pages in many situations without having to resort to a client-side framework such as Angular.

In that post, I mentioned that Blazor (which at that stage was at version 0.5.0) could improve things in the future. Blazor has since been released, and in many cases, it is a viable alternative to SPA frameworks. However, for me, it is still not feasible in many situations. Blazor Server suffers from latency and scalability issues, and Blazor WebAssembly has a big download size.

You can review the ASP.NET Core Blazor hosting models documentation which discusses the issues mentioned above.

I believe there is still a middle ground where you may be happy with using Razor Pages or MVC, but want to add sprinkles of interactivity to some of your pages to give a better user experience.

In this new series, I will introduce you to HTMX, a library that allows you to do this. It works in a very similar fashion to the now-deprecated jQuery Unobtrusive Ajax library which I used in the first series. I will also work through a few common scenarios and demonstrate how you can implement it with Razor Pages and HTMX.

This series consists of the following blog posts:

  1. Introduction (this blog post)
  2. Deleting items from a list
  3. Do a page refresh when deleting items
  4. Inline editing (coming soon)
  5. Infinite scrolling (coming soon)
  6. Real-time search (coming soon)

The HTMX library

HTMX is a library that allows you to add features such as AJAX and DOM updates to your web pages. Instead of requiring you to write JavaScript, HTMX enables you to add this functionality by adding some attributes to your HTML markup.

To get a better understanding of this model, let’s look at the following example from the HTMX website:

<button hx-post="/clicked" hx-swap="outerHTML">
    Click Me
</button>

You can see that we have a button element with two additional hx-* attributes defined.

  1. The hx-post attribute tells HTMX that when a user clicks on the button, it should perform an HTTP POST request to /clicked.
  2. The hx-swap attribute tells HTMX that it should replace the button element with the content from this request’s response.

We will cover HTMX in more detail in the remaining blog posts in this series, but you can also refer to the HTMX documentation if you want a better understanding of it.

Installing HTMX in an ASP.NET Core application

The quickest way to add HTMX to your ASP.NET Core application is to reference the script via UNPKG. To do that, add the following script to the Razor Pages where you want to use it:

<script src="https://unpkg.com/htmx.org@1.1.0" integrity="sha384-JVb/MVb+DiMDoxpTmoXWmMYSpQD2Z/1yiruL8+vC6Ri9lk6ORGiQqKSqfmCBbpbX" crossorigin="anonymous"></script>

The script above uses version 1.1.0, but you can refer to the installation section on the HTMX website for the latest version and installation instructions.

If you prefer to make use of LibMan, you can run the following command:

libman install htmx.org@1.1.0 --provider unpkg --files dist/htmx.min.js

Then, proceed to add the reference to the HTMX file as follows:

<script src="~/lib/htmx.org/dist/htmx.min.js"></script>

Conclusion

In this blog post, I gave you a brief introduction to this series and HTMX and demonstrated how you could add the HTMX library to your existing ASP.NET Core application. In the next blog post, I will show you how to use HTMX to delete items from a list.

You can find the source code for this series at https://github.com/jerriepelser-blog/htmx-with-aspnet-core.