Flask-HTMX

0.4.0 · active · verified Thu Apr 16

Flask-HTMX is a Flask extension that provides an easy API for working with HTMX from within a Flask request context. It simplifies integrating HTMX into Flask applications by enhancing the global request object and offering a specialized `make_response` function for HTMX-specific headers. The current version is 0.4.0, and the library maintains an active release cadence with regular updates.

Common errors

```
ModuleNotFoundError: No module named 'flask_htmx'
```
cause The `flask-htmx` package has not been installed in your Python environment or the virtual environment is not active.

fix Install the library using pip: `pip install flask-htmx`.
```
RuntimeError: The HTMX extension is not registered to the current application.
```
cause You are attempting to access or use the `htmx` object within a Flask request context before it has been properly initialized and registered with your Flask application.

fix Ensure you have initialized the extension either by passing the app object directly: `htmx = HTMX(app)`, or by calling `init_app()`: `htmx = HTMX(); htmx.init_app(app)`.
```
HTMX client-side headers (e.g., HX-Trigger, HX-Location) are not being sent or processed correctly by the browser, despite setting them in Flask.
```
cause You are likely using `flask.make_response` instead of `flask_htmx.make_response` to construct your responses. The standard `flask.make_response` does not provide the utility to automatically set HTMX-specific headers.

fix Replace `from flask import make_response` with `from flask_htmx import make_response` and use the provided keyword arguments for HTMX headers (e.g., `return make_response('content', trigger={'event': 'data'})`).

Warnings

breaking Older versions of `flask-htmx` (pre-0.3.2) may not be compatible with Flask 3.0.0 and later.
Fix: Upgrade `flask-htmx` to version 0.3.2 or newer by running `pip install --upgrade flask-htmx` to ensure compatibility with Flask 3.x.
gotcha Using `flask.make_response` for responses that require HTMX-specific headers (e.g., `HX-Redirect`, `HX-Push-URL`, `HX-Trigger`) will not correctly apply these headers.
Fix: Always import and use `make_response` from `flask_htmx` when generating responses that need HTMX headers. This function provides extended arguments for common HTMX response headers.
gotcha Before version 0.4.0, the `htmx` object was not automatically available as a global context variable in Jinja2 templates. You had to explicitly pass it to `render_template`.
Fix: For versions prior to 0.4.0, ensure you pass `htmx=htmx` in your `render_template` call (e.g., `render_template('index.html', htmx=htmx)`). In 0.4.0 and later, it's available globally as `htmx`.
gotcha When submitting forms via HTMX POST requests, especially if CSRF protection is enabled in Flask (e.g., with Flask-WTF), you must ensure the CSRF token is included in the HTMX request.
Fix: Include the CSRF token in your form or request data. For example, if using Flask-WTF, ensure your form includes `{{ form.csrf_token }}` or pass the token in hidden inputs for HTMX requests.

Install

pip install flask-htmx Install latest version

Imports

HTMX
wrong:
```
from flask_htmx.extension import HTMX
```
correct:
```
from flask_htmx import HTMX
```
The HTMX class is exposed directly from the top-level package.
make_response
wrong:
```
from flask import make_response
```
correct:
```
from flask_htmx import make_response
```
Use `flask_htmx.make_response` to easily add HTMX-specific response headers.

Quickstart

This quickstart demonstrates initializing Flask-HTMX and handling both regular and HTMX-triggered requests. It shows how to conditionally render partial content for HTMX requests and how to use `flask_htmx.make_response` to add HTMX-specific response headers, like `HX-Trigger`.

from flask import Flask, render_template
from flask_htmx import HTMX

app = Flask(__name__)
htmx = HTMX(app)

@app.route("/")
def home():
    if htmx:
        # HTMX request, return a partial template
        return render_template("partials/thing.html")
    # Normal browser request, return a full page
    return render_template("index.html")

@app.route("/click-me", methods=["POST"])
def click_me():
    # Example of using make_response for HTMX headers
    from flask_htmx import make_response
    return make_response("<span>Clicked!</span>", trigger={'myEvent': 'Data'})

view raw JSON →