htmx-spring-boot

The htmx-spring-boot project simplifies integrating htmx with Spring Boot and Spring Web MVC applications. It provides views, annotations, and argument resolvers to handle htmx-related request and response headers, facilitating AJAX-based partial page updates.

It also includes a custom Thymeleaf dialect to enable smooth rendering of htmx-specific attributes within Thymeleaf templates.

The library provides a Thymeleaf dialect that enables htmx-specific processing using the hx: prefix (instead of the static hx- prefix).

hx: attributes

Use hx:get, hx:post, etc., to allow Thymeleaf to evaluate expressions within htmx attributes. Example: <div hx:get="@{/users/{id}(id=${userId})}"> will render a valid htmx URL.

hx:vals with inline maps

You can write JSON for hx-vals more easily using Thymeleaf inline maps: Example: <div hx:vals="${ {id: user.id, groupId: group.id } }">

Warning: When using hx:target, avoid using the # symbol directly in the Thymeleaf expression (e.g., hx:target="#mydiv") as Thymeleaf interprets # as a translation key. Instead, use hx-target="#mydiv" or hx:target="${'#mydiv'}".

<div hx:get="@{/users/{id}(id=${userId})}" hx-target="#otherElement">Load user details</div

To enable the custom Thymeleaf dialect for working with htmx attributes in your templates, add the following dependency to your pom.xml:

<dependency>
    <groupId>io.github.wimdeblauwe</groupId>
    <artifactId>htmx-spring-boot-thymeleaf</artifactId>
    <version>LATEST_VERSION_HERE</version>
</dependency>

The following resources provide guidance on specific integration patterns between htmx and Spring MVC/Thymeleaf:

• Redirecting with attributes: How to handle Spring MVC redirect attributes when working with htmx.
• Authentication error handling: Best practices for managing htmx authentication errors.
• Out-of-band (OOB) swaps: Using Thymeleaf to implement htmx out-of-band swaps.

The Thymeleaf integration allows you to use Markup Selectors (e.g., template :: fragment) in your view names. This allows you to return only a specific part of a template, which is ideal for htmx updates and OOB swaps.

Example: Returning the list and count fragments from the users template.

@HxRequest
@GetMapping("/users")
public View users(Model model) {
    model.addAttribute("users", userRepository.findAll());
    model.addAttribute("count", userRepository.count());

    return FragmentsRendering
            .with("users :: list")
            .fragment("users :: count")
            .build();
}

To use the core annotations and helper classes for handling htmx requests and responses in your Spring Boot application, add the following dependency to your pom.xml:

<dependency>
    <groupId>io.github.wimdeblauwe</groupId>
    <artifactId>htmx-spring-boot</artifactId>
    <version>LATEST_VERSION_HERE</version>
</dependency>

To support htmx Out Of Band (OOB) swaps, you can return multiple HTML fragments from a single controller method. This is achieved by returning either a Collection<ModelAndView> or using the FragmentsRendering builder.

Using FragmentsRendering

This is the recommended way to build a collection of fragments to be sent in one response.

@HxRequest
@GetMapping("/users")
public View users(Model model) {
    model.addAttribute("users", userRepository.findAll());
    model.addAttribute("count", userRepository.count());

    return FragmentsRendering
        .with("users/list")
        .fragment("users/count")
        .build();
}

To access specific htmx request headers (like HX-Trigger, HX-Request, etc.) within your controller, include HtmxRequest as a method argument. This allows you to inspect the request state, such as whether it is a history restore request.

@HxRequest
@GetMapping("/users")
public String users(HtmxRequest htmxRequest) {
    if (htmxRequest.isHistoryRestoreRequest()) {
        // do something
    }
    return "view";
}

Use the @HxRequest annotation to ensure a controller method is only invoked if the request was made via htmx (e.g., via hx-get, hx-post, etc.).

Restricting by Trigger Element

You can restrict invocation to a specific triggering element by providing its ID or name to the @HxRequest value. For explicit control, use triggerId or triggerName:

• @HxRequest("my-element") (matches ID or name)
• @HxRequest(triggerId = "my-id")
• @HxRequest(triggerName = "my-name")

Restricting by Target Element

Use target to restrict invocation to requests targeting a specific element:

• @HxRequest(target = "my-target")

@HxRequest
@GetMapping("/users")
public String users() {
    return "view";
}