hx-requests

Full documentation: hx-requests Documentation Demo Website: https://hx-requests-demo.com/

Installation

pip install hx-requests

Requires Python 3.11+ and Django 4.2+.

Overview

What Are hx-requests?

To start with a high-level explanation, hx-requests are quasi Django + Htmx views. They mimic Django's class-based views but with added functionality to work seamlessly with Htmx. Using a View mixin, it elegantly handles multiple Htmx requests on a single page. Each Htmx request is routed to a specific hx-request (think of it as a view), which returns the necessary HTML to update the DOM. A more detailed explanation can be found below.

Why The Name?

Excellent question! The package was named early on in the development process when the behavior wasn't exactly clear. All that was clear was that there needed to be an easier way to work with Htmx in Django. Hx comes from Htmx, and requests because every use of Htmx is a request to the server. If it was named today, it would probably be called something like Django-Htmx-Views, but hx-requests has stuck.

Why Use hx-requests?

This is where we will get into the details of why hx-requests is needed.

There are multiple ways of integrating Htmx in a Django project.

1. Using The Page View

The most common way is re-hitting the view that loaded the page.

The base view:

class MyView(View):
    def get(self, request):
        return render(request, "my_template.html")

The template:

<div hx-get="{% url 'my_view' %}">
    <p>Click me to use hx-get</p>
</div>

Handling the request:

class MyView(View):
    def get(self, request):
        if request.headers.get("HX-Request"):
            return render(request, "my_template.html")
        return render(request, "my_template.html")

This approach works well for views with one Htmx request, but what if you have multiple Htmx requests on the same page?

Handling multiple Htmx requests:

class MyView(View):
    def get(self, request):
        if request.headers.get("HX-Request"):
            if request.headers.get("Unique-Identifier") == "get_user_info":
                return render(request, "user_info_card.html")
            if request.headers.get("Unique-Identifier") == "get_user_profile":
                return render(request, "user_profile_card.html")
        return render(request, "my_template.html")

Issues with this approach:

It gets messy if there are multiple Htmx requests on the same page.
Handling POST requests with specific logic dynamically adds complexity.
The logic for handling Htmx requests is tightly coupled to the view, making reuse difficult.

2. Using Separate Views

Each Htmx request is routed to a separate view.

# Page View
class MyView(View):
    def get(self, request):
        context = {'complex-context': "This is a complex context"}
        return render(request, "my_template.html", context)

# Htmx Request 1
class GetUserInfo(View):
    def get(self, request):
        return render(request, "user_info_card.html")

# Htmx Request 2
class GetUserProfile(View):
    def get(self, request):
        return render(request, "user_profile_card.html")

Issues with this approach:

Each Htmx request requires a separate URL.
Context is not shared across views, leading to code duplication.
Using Django's built-in ListView, duplicating logic for Htmx requests becomes a nightmare.

hx-requests: The Solution

hx-requests solves all of these issues. It allows multiple Htmx requests on the same page while sharing context across requests. Every Htmx request routes to an hx-request.

Advantages:

The parent view is not cluttered with extra logic for handling multiple Htmx requests.
HxRequests are reusable across views, reducing duplication.
No extra URLs are needed.
The view's context is shared across all Htmx requests, making it easier to manage.

Additionally, hx-requests includes built-in functionality to help with common Htmx use cases:

Form validation and automatic return of errors when using FormHxRequest.
Easy integration with Django's messages framework.
Compatibility with django-render-block for partial template rendering.
Built-in support for handling modals with Htmx.

Full documentation: hx-requests Documentation

Contributing to this repository

Getting setup

This project is using poetry
pre-commit is used for CI (code formatting, linting, etc...)
There is a dev container that can be used with vs-code

Committing

Must follow Conventional Commit

Metadata

Release files for hx-requests 0.56.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for hx-requests 0.56.0
File	Size	Uploaded
hx_requests-0.56.0.tar.gz	28.4 kB	Jul 31, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for hx-requests 0.56.0
File	Interpreter	ABI	Platform	Reset
hx_requests-0.56.0-py3-none-any.whl 30.2 kB Jul 31, 2026	Python 3	none	any	Details

Total release size: 58.6 kB

Release files / hx_requests-0.56.0.tar.gz

Download URL	hx_requests-0.56.0.tar.gz
Size	28.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`60a8fa925b7849b3d65ba4569ba44c7e05f076bf7969e2d01ab0905f74f8fada`
BLAKE2b-256 checksum How to use checksums	`32baea8db85c4a0938f39c948a7f29abf9e0a051f63eb68ea0407b7fa3e05002`
Upload date	Jul 31, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/1.8.5 CPython/3.8.18 Linux/6.17.0-1020-azure`

Release files / hx_requests-0.56.0-py3-none-any.whl

Download URL	hx_requests-0.56.0-py3-none-any.whl
Size	30.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`ba0d81133885ecd89668d023575cecbac9bb41f095bd63d22d584335432ef8c2`
BLAKE2b-256 checksum How to use checksums	`2ecc71f484a2b345b5e46b3fbffbfa018ed247efea5b237cfdb853871e6727a7`
Upload date	Jul 31, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/1.8.5 CPython/3.8.18 Linux/6.17.0-1020-azure`