Template Partials & htmx

A server-rendered page is a tree of HTML that the server produces from a template. When a small part of the page has to change after the page has loaded (a search box narrows a table, a button toggles a flag, a form shows its errors) there are three ways to do it. Reload the whole page, which is simple but throws away scroll position, focus and typed text. Send JSON and write JavaScript that rebuilds the HTML, which duplicates the template on the client. Or ask the server for just the changed fragment and swap it into the page, which is what htmx automates. The third way needs the server to be able to render a piece of a template. Before Django 6.0 that meant splitting every fragment into its own small file and including it from the page with {% include %}, or installing a third-party package. Two files per feature, one for the page and one for each fragment, made the page harder to read because its pieces were scattered across the project.

Template partials keep the page and its fragments in one file. The fragment is defined once, rendered inside the page for a normal request, and rendered on its own for an htmx request, with the same context and the same auto-escaping.

{% partialdef name %} opens a partial and {% endpartialdef %} closes it. The name is required and must be a valid template identifier; hyphens are fine (book-table). The closing tag may repeat the name ({% endpartialdef book-table %}), which helps when partials are long or nested. {% partial name %} renders the partial at that point. The partial is rendered with the current context each time it is used, so it works inside {% for %} loops and under {% with %}, and its output is auto-escaped like any other template output. A partial is not a function with arguments: it sees whichever variables are in the context where it is used, and {% with %} is how you change them for one use.

Rendered with the context {"x": "<b>", "title": "plain"} this produced <p><b></p><p>plain</p>: escaping is applied inside the partial and {% with %} changed the variable only for the first use. A partial can even be used before the place where it is defined ({% partial card %}{% partialdef card %}hi{% endpartialdef %} rendered hi), because the definitions are collected when the template is compiled, but defining first reads better.

Source: The Django template language: Template partials

Appending #name to a template name selects one partial of that template. It works wherever Django accepts a template name: the render() shortcut, get_template(), render_to_string() and {% include %}. Only the partial is rendered, but the template’s other partials are available to it, so a partial can use its siblings.

An unknown partial name raises TemplateDoesNotExist, the same exception as for a missing file, so a typo is caught by the first test that renders it (the scratch suite asserts exactly that). Because the whole template is compiled and only a part is rendered, anything outside the chosen partial costs nothing at render time: in the scratch project a {% for %} over a queryset outside the partial ran one query when the whole template was rendered and none when #p was rendered. A lazy queryset that the fragment does not use is therefore never evaluated.

Source: The Django template language: Accessing partials directly

The # syntax belongs to Django’s own template engine and to its template loaders, so this page’s examples target the Django Template Language. The Jinja2 backend (see Templates) is a separate engine and the partial tags are documented for the Django template language only.

Nothing about a partial changes the cycle described in the request/response cycle: the URL resolver picks a view, middleware runs around it, and the view returns an HttpResponse. The only difference is the name passed to render(). A partial request still passes through every middleware (sessions, authentication, CSRF), so a fragment is exactly as protected as the page, but also exactly as unprotected: a fragment URL is a normal URL that anybody who can guess it can request, so permission checks belong in the view (or a decorator), never in the assumption that "only the page links here". Template rendering is synchronous in both sync and async views, and in an async view the ORM must not be touched from inside the template; evaluate the queryset in the view before rendering. django_htmx.middleware.HtmxMiddleware supports sync and async modes.

htmx is a small JavaScript library that lets any HTML element issue an HTTP request and swap the HTML in the response into the page, using attributes instead of JavaScript. The page is the hypermedia: the server answers with HTML, not JSON. The attributes that matter for a Django developer are these.

Every request htmx makes carries an HX-Request: true header, which is how the server tells an htmx request from a normal navigation. htmx 2 swaps responses with 2xx and 3xx status codes, ignores 204, and by default does not swap 4xx and 5xx responses; that behaviour is configurable through htmx.config.responseHandling and matters for form validation below.

Source: htmx documentation

The central pattern is a single view that serves the full page to a normal request and just the table to an htmx request. The template defines the table as an inline partial, so a normal request renders it inside the page and an htmx request selects it with #book-table.

The search box sends GET /books/?q=…​ 300 milliseconds after the user stops typing and only if the value changed; the response replaces the table (hx-target="#book-table" with outerHTML, so the response must itself be a <table id="book-table">, which is why the partial includes the <table> tag), and hx-push-url makes the filtered URL bookmarkable. The row partial is used by the table and, as the next section shows, by a second view. A curl session against runserver shows both renderings of the same URL:

The first response is the whole document (1093 bytes, with the <h1>, the search box and both books); the second contains only the filtered table (274 bytes). Both responses carry Vary: HX-Request, which is not optional. One URL now has two possible bodies, so a browser cache, a CDN or Django’s cache middleware must key the cached copy on the HX-Request header, or the fragment can be served to a browser that asked for a page, and the other way round. Add the header with vary_on_headers (shown above) or patch_vary_headers; the cache middleware and its ordering are covered in Middleware. The same caution applies to htmx’s history: when a user navigates back to a page that htmx pushed into history and the browser cache has missed, htmx re-requests the URL expecting a complete page, so a pushed URL must always be able to return the whole page; htmx documents htmx.config.historyRestoreAsHxRequest for this case, and the django-htmx middleware exposes request.htmx.history_restore_request.

The test client sends an htmx request by setting the header itself; no JavaScript is needed to test the server side.

Source: django-htmx: Partial Rendering and View decorators: vary_on_headers

A button inside a table row needs the row back, not the whole table. The second view returns the row partial through catalog/book_list.html#row, and the button replaces its own row with hx-target="#book-<pk>" and outerHTML.

The view follows the usual rules: only signed-in editors may change the flag (login_required redirects anonymous visitors to the login page and permission_required answers 403 to users without catalog.change_book, because in this example favourite is a catalogue-wide flag curated by staff; per-reader favourites would be a many-to-many relation to the user, with the query scoped to request.user), state changes use POST (require_POST answers a GET from an editor with 405), and CSRF protection stays on (a POST without a token answers 403 before the view runs). The 405 and 403 were verified with curl against the view without the two access decorators; with them, an anonymous request is redirected to the login page first. Because the row is a partial of the same template as the table, the markup of a row exists in exactly one place; change the row and both the page and the swap change.

Source: The Django template language: Accessing partials directly

Django’s CSRF middleware rejects an unsafe request without a valid token, and htmx’s hx-post is such a request. Django accepts the token in the x-csrftoken header (CSRF_HEADER_NAME can change it, and there is rarely a reason to), and the neat way to send it from every htmx request is hx-headers on the <body>, which every element inherits. The value must be the variable {{ csrf_token }}, not the tag {% csrf_token %}, which renders a hidden <input>.

That attribute is already in the book_list.html listing above, and the row test proves it matters: the Django test client disables CSRF checks by default, so the test builds a client with enforce_csrf_checks=True and asserts that a token-less POST is answered with 403. Forms rendered inside a fragment can instead keep {% csrf_token %} in the form, as the next section does; both mechanisms are the same protection (see Middleware for CsrfViewMiddleware).

Source: django-htmx: Make htmx pass Django’s CSRF token

The most valuable use of partials is a form: the page renders it normally, and when the submission is invalid the server re-renders just the form with its errors and htmx swaps it back. The form is a partial of a template that extends a base, so this also shows partials inside {% block %}.

Four details make this work. The form has both a normal method/action and the htmx attributes, so without JavaScript it is a plain form post (this is progressive enhancement: htmx is an improvement, not a requirement). An invalid submission answers with status 422 and, for htmx, only the form partial; htmx 2 would not swap a 4xx response by default, so the htmx-config meta tag adds 422 to the swapped codes, following the htmx documentation’s own example. A normal (non-htmx) invalid post gets the full page, also with status 422. A valid htmx submission cannot just redirect(), because the browser would follow the redirect inside the AJAX request and htmx would swap the whole destination page into the form; instead the view answers with HttpResponseClientRedirect, which sends the HX-Redirect header and makes htmx navigate the browser, while a normal submission gets a normal HttpResponseRedirect. These four behaviours are pinned by tests:

The model form lists its fields explicitly, as every form in this section does; see Models and Fields for the model, and the forms pages of this section for validation, widgets and rendering with as_div.

Source: htmx: Requests and response handling and django-htmx: HTTP tools

htmx lets the server steer the browser through response headers, and django-htmx wraps them in classes and functions so that no header name is typed by hand. The response classes are HttpResponseClientRedirect (HX-Redirect), HttpResponseClientRefresh (HX-Refresh), HttpResponseLocation (HX-Location, a client-side boosted navigation with optional target, swap and select) and HttpResponseStopPolling (status 286, which stops an hx-trigger="every …​" poll). The functions take a response and return it with a header set: push_url (HX-Push-Url), replace_url, reswap, retarget, reselect, and trigger_client_event, which fires a browser event that other elements can listen for with hx-trigger="book-saved from:body". The form view above used two of them.

Rendering the form partial with those two calls returned status 422 with the headers HX-Retarget: #form-errors and HX-Reswap: innerHTML. These helpers keep the markup simple: the same fragment can be sent to different places depending on what the server decided, without teaching the page about every outcome.

Source: django-htmx: HTTP tools

{% htmx_script %} renders <script> tags with the defer attribute for the htmx copy that django-htmx vendors, so there is no CDN request: serving scripts from your own origin is better for privacy, performance and security, and it is what the django-htmx documentation recommends for htmx extensions too (download them into your static files instead of loading them from a public CDN). Pass minified=False while debugging, version=4 to opt into htmx 4 (beta at the time of writing, and there is no htmx 3: the project went from 2 to 4), and extensions="hx-sse,hx-ws" for vendored extensions named as in htmx 4. With Django 6.0’s Content Security Policy support (covered in the security and CSP page of this section), the tag adds the CSP nonce to the <script> tags when one is present in the template context, so the page can keep a strict script-src without allowing inline scripts. Note that htmx itself uses eval for a few features (event filters, hx-on attributes, hx-vals with the js: prefix); htmx.config.allowEval can switch them off if the policy forbids it.

Rendering that tag with csp_nonce in the context produced <script src="/static/django_htmx/htmx-4.min.js" defer nonce="abc">, the hx-sse extension script with the same nonce, and, because DEBUG was on, the django-htmx debug script.

Source: django-htmx: Template tags

Partials are the cleanest, but two older techniques still appear in codebases. Splitting each fragment into its own file and using {% include %} works on any Django version and is perfectly fine for a fragment shared by many pages. Swapping the base template (a context variable used in {% extends base_template %}, set to a minimal wrapper for htmx requests) renders the whole page body but without the layout; it suits "boosted" navigation where the whole <main> changes. Each of these shows up in the django-htmx tips. Neither makes a page easier to read than a partial does, but the base-swap technique remains the right tool when the fragment is a whole page.

Fragments are easy to test because they are plain responses. Send the HX-Request header with the test client (headers={"HX-Request": "true"}), assert on the markup with assertContains(…​, html=True), assert the status and the HX-* response headers, and add one test per variation (full page, fragment, invalid fragment). The scratch suite has 15 tests for this page’s examples and ran in 0.015 seconds. Browser-level behaviour (the swap really happening, focus kept, history updated) belongs in an end-to-end test; see end-to-end testing with real browsers.

Source: Testing tools

A single-page application (React, Vue or Angular, see React, Vue and Angular) moves rendering to the browser and turns the server into a JSON API. A Django site with partials and htmx keeps rendering on the server and adds interactivity by fragment. Neither is better in general; the choice is about what the product is.

A pragmatic rule is to start with Django templates and htmx and to reach for a SPA when a specific screen needs client-side state that cannot be expressed as "ask the server for a new fragment". The two are not exclusive: a Django site can serve most pages as HTML and mount a JavaScript widget on one page, and the DRF and Django Ninja pages of this section show how the same models are served as JSON for the pages and apps that do need it. The htmx project’s own essays discuss when hypermedia is the right fit and where it is not.

Source: htmx essay: When Is HTML Replacement Going To Be Better?

Before Django 6.0 the same idea was provided by the third-party django-template-partials package: you installed it, listed it in INSTALLED_APPS, wrote {% load partials %} in each template and used the same partialdef / partial tags and the template#partial name syntax. The Django 6.0 release notes link to a migration guide in the package’s repository. The migration is small: remove the app from INSTALLED_APPS, delete the {% load partials %} lines (the tags are built in), and uninstall the package. The latest release of the package at the time of writing is 25.3, whose classifiers stop at Django 6.0.

Django 5.2 LTS (supported until April 2028) has no built-in partials, so a project that stays on 5.2 should keep the package and plan the removal for the move to 6.x. django-htmx 1.29.0 supports Django 5.2 to 6.1, so the htmx half of this page works unchanged on 5.2, and only the {% partialdef %} / {% load partials %} difference needs attention.

Source: Django 6.0 release notes: Template partials and django-template-partials: Migration guide

The four reference books this section was cross-checked against were written for Django 1.11–2.1, long before template partials existed in Django 6.0, so they cannot describe the built-in tags; where they discuss reusable template pieces the tool they have is {% include %} with one file per fragment. Two older idioms in this area should not be copied into new code. Detecting AJAX with request.is_ajax() was removed in Django 4.0 (replace it with a header such as HX-Request, and with request.htmx when django-htmx is installed), and the django-template-partials package is no longer needed from Django 6.0 on. The books also predate htmx (first released in 2020) and the hypermedia approach described here.

Source: Django 6.0 release notes and django-htmx documentation