ko-sasaki / htmx-spring-boot-thymeleaf

Spring Boot and Thymeleaf helpers for working with htmx

Spring Boot and Thymeleaf library for htmx

This library provides helper classes and a Thymeleaf dialect to make it easy to work with htmx in a Spring Boot application.

More information about htmx can be viewed on their website.

Installation

The library is available on Maven Central, so it is easy to add the dependency to your project.

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

Usage

Configuration

The included Spring Boot autoconfiguration will enable the htmx integrations.

Request Headers

See Request Headers Reference for the related htmx documentation.

Methods can be annotated with @HxRequest to be selected when an htmx-based request (ie hx-get) is made.

@GetMapping("/users")
@HxRequest                  // Called when hx-get request to '/users/' is made 
public String htmxRequest(HtmxRequest details){
    service.doSomething(details);

    return "partial";
}

@GetMapping("/users")        // Only called on a full page refresh, not an htmx request
public String normalRequest(HtmxRequest details){
    service.doSomething(details);

    return "users";
}

These annotations allow for composition if you wish to combine them, so you could combine annotations to make a custom @HxGetMapping.

Using HtmxRequest to inspect HTML request headers

The HtmxRequest object can be injected into controller methods to check the various htmx request headers.

@GetMapping
@ResponseBody
public String htmxRequestDetails(HtmxRequest htmxReq) { // HtmxRequest is injected
    if(htmxReq.isHistoryRestoreRequest()){
        // ...
    }

    return "";
}

Response Headers

See Response Headers Reference for the related htmx documentation.

Setting the hx-trigger header triggers an event when the response is swapped in by htmx. The @HxTrigger annotation supports doing that for you:

@GetMapping("/users")
@HxRequest
@HxTrigger("userUpdated") // 'userUpdated' event will be triggered by htmx
public String hxUpdateUser(){
    return "users";
}

Processors

See Attribute Reference for the related htmx documentation.

Thymeleaf processors are provided to allow Thymeleaf to be able to perform calculations and expressions in htmx-related attributes. Note the : colon instead of the typical hyphen.

• hx:get: This is a Thymeleaf processing enabled attribute
• hx-get: This is just a static attribute if you don't need the Thymeleaf processing

For example, this Thymeleaf template:

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

Will be rendered as:

<div hx-get="/users/123" hx-target="#otherElement">Load user details</div>

The included Thymeleaf dialect has corresponding processors for most of the hx-* attributes. Please open an issue if something is missing.

Note Be careful about using # in the value. If you do hx:target="#mydiv", then this will not work as Thymeleaf uses the # symbol for translation keys. Either use hx-target="#mydiv" or hx:target="${'#mydiv'}"

OOB Swap support

htmx supports updating multiple targets by returning multiple partial response with hx-swap-oop. Return partials using this library use the HtmxResponse as a return type:

@GetMapping("/partials/main-and-partial")
public HtmxResponse getMainAndPartial(Model model){
        model.addAttribute("userCount",5);
        return new HtmxResponse()
            .addTemplate("users :: list")
            .addTemplate("users :: count");
}

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

License

Apache 2.0

Release

To release a new version of the project, follow these steps:

1. Update pom.xml with the new version and commit
2. Tag the commit with the version (e.g. 1.0.0) and push the tag.
3. Create a new release in GitHub via https://github.com/wimdeblauwe/htmx-spring-boot-thymeleaf/releases/new
   • Select the newly pushed tag
   • Update the release notes. This should automatically start the release action.
4. Update pom.xml again with the next SNAPSHOT version.
5. Close the milestone in the GitHub issue tracker.