Use HTMX with Blazor SSR

08/10/2024 15:43:34 - Edited: 04/18/2025 15:01:50

HTMX, Blazor, .Net

3 min read

In this article I will show how to setup a Blazor SSR project together with HTMX.

Why?

The popularity rise of HTMX is truly a sight to behold and understandably so. It feels like the perfect option for people who are familiar in a backend language and want to build a website but dont want to have to fuss around with JavaScript.

As a C# developer myself I had worked with Blazor before, albeit in a WASM context, and loved its syntax. The marriage of the powerfull ecosystem of .Net in the backend paired with the efforless client side functionality through HTMX seems like a match made in heaven.

How?

With the introduction of Blazor SSR in .Net 8 we gained even more options of how to build out our Blazor application. Fine grained control of which interactivity model to use for which page. Yet today we don't care about the interactivity that .Net itself provides.

To get started:

Create a new Blazor Web App project.
For the interactive render mode choose None as that will be handled by HTMX.
For the interactivity location choose Per page/component.

Once the project has been created the fist step is to add HTMX. The easiest way to do so, is by pulling it from a CDN. For this navigate to the App.razor file and switch out the blazor.web.js script for the HTMX one

<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <base href="/" />
    <link rel="stylesheet" href="app.css" />
    <link rel="stylesheet" href="BlazorApp1.styles.css" />
    <HeadOutlet />
</head>

<body>
    <Routes />
    <script src="https://unpkg.com/htmx.org@2.0.1"></script>
</body>

</html>

Loading HTMX from a CDN is okay but not ideal. Preferrably the sources should be hosted by you as well. An elegant way to do say will be shown in a later blog post. For now this will suffice.

Rendering fragments

Now that we have our basic setup for HTMX completed we can implement a first small demo of how to use it.

For this we first need to create a new layout. This is important because with HTMX we want to be able to send partial HTML pages. So we need an empty layout. For this create an EmptyLayout.razor with the following content

@inherits LayoutComponentBase

@Body

This layout will be used for the pages that return partial HTML.

Next create a new Razor component that simply returns a paragraph.

@page "/content"
@using BlazorApp1.Components.Layout
@layout EmptyLayout

<p>Congratulations you're using HTMX</p>

@code {

}

We have now created a component that can be loaded from the client upon a user action. When the "/content" path is called, i.e. a get-request is made against that url we send back the HTML.

Putting it together

With our newly created component in mind we can now modify our Home.razor to actually put HTMX to use. We simply create a button with an hx-get attribute that matches the route of the component we created before.

@page "/"

<PageTitle>Home</PageTitle>

<div>
    <h1>Nothing to see here</h1>
    <button hx-get="/content">
        Click me
    </button>
</div>

When the button is pressed a get request is made to "/content" and the button is swapped with whatever is returend. With this, the basic setup to build Webapps with Blazor SSR and HTMX is complete. This is of course only a tiny piece of building an actual application. To get started with HTMX itself I cannont reccomend its documentation and examples enough.