hx-vals serializes null values differently from hidden inputs, causing 'null' being printed.

[JBraddockm]

Hi all,

Issue Summary

When using hx-vals instead of hidden input fields for address lookup data from OpenStreetMap, null values are handled differently.

Current Behavior

Hidden inputs: Empty properties are serialized as empty strings ("")
hx-vals: Empty properties are serialized as null in the JSON output, which is expected given that null is a valid value in JSON. Thymeleaf prints out 'null' in the UI.

Example Use Case

I'm building an address lookup component using OpenStreetMap data. Some addresses have optional fields (like building names) that may be null. While this worked fine with hidden inputs, switching to hx-vals caused 'null' being printed in the UI.

Current Workaround

Given that HtmxThymeleafAutoConfiguration uses a standard JsonMapper, I've implemented a custom HtmxDialect configuration that forces null values to be serialized as empty strings:

@Configuration
public class HtmxDialectConfig {

  @Bean
  @Primary
  public HtmxDialect customHtmxDialect() {
    JsonSerializer<Object> nullSerializer =
        new JsonSerializer<>() {
          @Override
          public void serialize(Object value, JsonGenerator gen, SerializerProvider serializers)
              throws IOException {
            gen.writeString("");
          }
        };

    JsonMapper jsonMapper = JsonMapper.builder().build();

    jsonMapper.getSerializerProvider().setNullValueSerializer(nullSerializer);

    return new HtmxDialect(jsonMapper);
  }
}

Questions

• Are there potential side effects to serializing null values as empty strings in HtmxDialect?
• If hx-vals is meant to replace hidden inputs, should it handle null values consistently with hidden inputs?
• Is there a better approach to handling optional fields in this context?

When working with external APIs like OpenStreetMap, null values are common for optional fields. While we could handle null checks explicitly, it would be more convenient if hx-vals behaved consistently with hidden inputs.

Thank you.

[wimdeblauwe]

How are you using hx-vals in your HTML templates exactly?

[JBraddockm]

The keyup changed triggers a request to address look up endpoint after three characters, which in return populates the dropdown menu with queries it performs on Open Street Map API, and renders the following fragment.

<!--/*@thymesVar id="location" type="....NominatimAPIResponseDTO"*/-->
<ul id="address-lookup-results" tabindex="0"
    class="dropdown-content z-[1] menu p-2 shadow bg-base-100 rounded-box w-full"
    th:fragment="address-lookup">
    <li th:each="location : ${locations}" th:object="${location}">
        <form th:hx-post="@{/addresses/select}" hx-target="#address-fields" hx-swap="outerHTML"
              hx-trigger="click"
              hx-on::after-request="if(event.detail.successful) document.getElementById('address-lookup-search').value = ''">
            <input type="hidden" name="buildingName" th:value="*{address.buildingName}"/>
            <input type="hidden" name="houseNumber" th:value="*{address.houseNumber}"/>
            <input type="hidden" name="road" th:value="*{address.road}"/>
            <input type="hidden" name="city" th:value="*{address.city}"/>
            <input type="hidden" name="postalCode" th:value="*{address.postalCode}"/>
            <p th:text="*{displayName}"></p>
        </form>
    </li>
</ul>

When the user selects an address, it then pass this data to another endpoint to populate the address fields in the screenshot above while resetting the input value. The address fields fragment also does a oob-swap to reset the dropdown results. I am still working on simplifying the flow so that I probably won't need to pass this data from one fragment to another.

Regardless, as I was reading the HTMX documentation, and your hx-vals implementation, I wanted to see how it would work in this scenario. So, if I swapped the hidden form fields with the following, everything still works as expected.

        <button type="button" 
                th:hx-post="@{/addresses/select}" 
                hx-target="#address-fields" 
                hx-swap="outerHTML"
                hx-trigger="click"
                th:text="*{displayName}"
                hx:vals="${ {buildingName:location.address.buildingName,houseNumber:location.address.houseNumber,road:location.address.road,city:location.address.city, postalCode:location.address.postalCode} }"
                hx-on::after-request="if(event.detail.successful) document.getElementById('address-lookup-search').value = ''">
        </button>

However, if any of the values are null in the Open Street Maps API response, then 'null' would be printed, as seen in the screenshot above.

[wimdeblauwe]

If the JSON that is sent is something like {"buildingName":null, ...}, then I don't think there is anything wrong and that null value should be handled when rendering in the visible text input in the UI. Unless it is rendered as {"buildingName":"null", ...} currently?

[JBraddockm]

No, it is rendered as {"buildingName": null, ...} without a custom null serializer. Only when it hits the controller, it is binded as ‘null’. As far as JSON is concerned, you are right that this is the expected behaviour.

However, correct me if I understand this incorrectly, hx:vals is being suggested as a replacement for hidden form inputs. But, it behaves differently for null values as far as how Thymeleaf treats empty inputs. If this were a critical or required field, proper validation and handling would be necessary. However, in this case, address fields are neither required nor subject to validation.

[wimdeblauwe]

Maybe it would be convenient if you could create a small reproducer to better understand exactly what is going on?

[JBraddockm]

Here is a repository to reproduce the behaviour. I added debugging details to the description.