HTMX Patterns - Preserving Query Parameters

I've been using HTMX quite a lot lately and I'm sold on the idea of the Hypertext Driven Application (HDA for short). For a thorough introduction into the topic I recommend going through the book.

When working with HTMX, I try to make use of the tools the Platform (aka the browser) provides. Part of that is making comprehensive use of URLs, which - when used correctly - make a web application sharable, discoverable and in general a good citizen in the web.

The problem

Let's say you have a list of items that's getting out of hand. To make it more manageable for the user we want to add pagination and search.

Let's first see a naive solution that does not quite work, followed by different solutions, all with different pros and cons. As always: it's a trade-off.

The naive solution

{% extends "layout.html" %}

{% block content %}
  <h1>Contacts</h1>
  <form action="">
    <input type="search" name="q" value="{{ request.GET.q }}">
  </form>
  <ul id="results">
    {% for contact in contacts %}<li>{{ contact.name }} - {{ contact.email }}</li>{% endfor %}
  </ul>
  <div>
    {% if contacts.has_previous %}<a href="?page={{ contacts.previous_page_number }}">Previous</a>{% endif %}
    {% if contacts.has_next %}<a href="?page={{ contacts.next_page_number }}">Next</a>{% endif %}
  </div>
{% endblock content %}

This should pretty self-explanatory, so I'll just highlight the problem here: The search term is lost when we change pages, since it's not persisted in the query parameters. This is actually quite easy to forget and of course gets amplified when more query parameters are involved. Even in the official book this problem exists, when the initial paginated design is enhanced with an active search.

Using forms instead of links

{% extends "layout.html" %}
{% block content %}
  <h1>Contacts</h1>
  <form>
    <input type="search" name="q" value="{{ request.GET.q }}">
  </form>
  <ul id="results">
    {% for contact in contacts %}<li>{{ contact.name }} - {{ contact.email }}</li>{% endfor %}
  </ul>
  <div>
    {% if contacts.has_previous %}
      <form method="get">
        <input type="hidden" name="page" value="{{ contacts.previous_page_number }}">
        <input type="hidden" name="q" value="{{ request.GET.q }}">
        <button>Previous</button>
      </form>
    {% endif %}
    {% if contacts.has_next %}
      <form method="get">
        <input type="hidden" name="page" value="{{ contacts.next_page_number }}">
        <input type="hidden" name="q" value="{{ request.GET.q }}">
        <button>Next</button>
      </form>
    {% endif %}
  </div>
{% endblock content %}

This might be a bit unconventional, but at least it does not suffer the same problem as the naive version. What we're doing here, is using hidden form inputs to carry the search term information when using the pagination.

Of course a pretty serious drawback is that we're now using buttons where links would be much better in terms of semantics, accessibility and UX. Having a button instead of a links removes some pretty handy browser features, like middle-clicking to open in a new tab or hovering over the link to show the destination of the link.

In terms of readability and composability I like this solution though, since there's no manual string formatting needed. All the "logic" of which parameters are being preserved is part of the HTML. If in this particular instance that's actually a good thing is questionable, though.

Using hx-include

{% extends "layout.html" %}
{% block content %}
  <h1>Contacts</h1>
  <form>
    <input type="search" name="q" id="search" value="{{ request.GET.q }}">
  </form>
  <ul id="results">
    {% for contact in contacts %}<li>{{ contact.name }} - {{ contact.email }}</li>{% endfor %}
  </ul>
  <div hx-boost="true">
    {% if contacts.has_previous %}
      <a hx-include="#search" href="?page={{ contacts.previous_page_number }}">Previous</a>
    {% endif %}
    {% if contacts.has_next %}
      <a hx-include="#search" href="?page={{ contacts.next_page_number }}">Next</a>
    {% endif %}
  </div>
{% endblock content %}

As it often seems to be the case, with just a few annotations we can tweak an existing solution using HTMX attributes. As you might have noticed, in the previous examples we weren't even using HTMX for our page.

It turns out, that it's enough to add the hx-include attribute to our anchor elements alongside enabling HTMX for them using the hx-boost attribute. What this does is effectively telling HTMX to include the value(s) of the matched inputs in the request. Instead of just including specific inputs another viable approach might be to use a data attribute on the to-be-included inputs and then filter using that, i.e. hx-include="[data-preserve-query]" .

The only downsides I can see with this solution is that hovering over the links won't reveal their true destination (because the query parameter q will be added by HTMX for the actual request) and that without JavaScript enabled, we're back to the original buggy behavior.

Using a better paginator

For the previous solutions, I've been using the standard Django paginator like so:

def contacts(request):
    contacts = all_contacts
    if q := request.GET.get("q"):
        contacts = [c for c in all_contacts if q in c["name"]]

    paginator = Paginator(
        object_list=contacts,
        per_page=10,
    )
    page = paginator.get_page(request.GET.get("page"))
    context = {"contacts": page}
    return TemplateResponse(request, "contacts.html", context)

The "problem" with this paginator is that it is completely oblivious of the context it is running in. Just as an idea, here's an enhanced version of the standard Paginator, which is bound to the request and knows how to generate the next and previous URLs we so desperately tried to construct ourselves previously:

from urllib.parse import urlparse, urlunparse, urlencode
from django.http import HttpRequest
from django.template.response import TemplateResponse
from django.core.paginator import Paginator

class BoundPaginator(Paginator):
    """A paginator that can generate URLs for the current page and the next and previous pages.

    Unlike Django's built-in Paginator, this one can generate URLs by being passed a request and
    a base URL. It also allows you to specify which query parameters to preserve when generating
    URLs.
    """

    def __init__(
        self,
        *args,
        page_param: str,
        preserve: list[str],
        request: HttpRequest,
        base_url: str = "",
        **kwargs,
    ):
        super().__init__(*args, **kwargs)
        self.base_url = base_url
        self.page_param = page_param
        self.preserve = preserve
        self.request = request

    def current_page(self):
        number = self.current_page_number()
        return self.page(number)

    def current_page_number(self) -> int:
        number = self.request.GET.get(self.page_param) or 1
        return int(number)

    def next_page_url(self):
        page = self.current_page()
        if page.has_next():
            return self.page_url_for_number(page.next_page_number())

    def previous_page_url(self):
        page = self.current_page()
        if page.has_previous():
            return self.page_url_for_number(page.previous_page_number())

    def page_url_for_number(self, number):
        result = urlparse(self.request.get_full_path())

        query_dict = {}
        for param in self.preserve:
            if value := self.request.GET.get(param):
                query_dict[param] = value

        result = result._replace(
            path=self.base_url,
            query=urlencode(query_dict, doseq=True),
        )

        return urlunparse(result)

While this seems to be quite overkill for such a simple task, it simplifies our template quite a bit, leaving us almost where we started:

{% extends "layout.html" %}
{% block content %}
  <h1>Contacts</h1>
  <form action="/contacts">
    <input type="search" name="q" value="{{ request.GET.q }}">
  </form>
  <ul id="results">
    {% for contact in contacts %}<li>{{ contact.name }} - {{ contact.email }}</li>{% endfor %}
  </ul>
  <div>
    {% if contacts.has_previous %}
      <a href="{{ contacts.paginator.previous_page_url }}">Previous</a>
    {% endif %}
    {% if contacts.has_next %}
      <a href="{{ contacts.paginator.next_page_url }}">Next</a>
    {% endif %}
  </div>
{% endblock content %}

Conclusion

So there you have it. A possibly much too thorough look at how to work with query parameters. To me, the hx-include approach probably will be just enough most of the time.

All the code for this blog is available in this repo for you to play around with. Have fun!