fswd

What is HTMX?

4 min read #Django #HTMX

What is HTMX?

Published: A practical guide to modern web development with Django

Introduction

If you're reading this blog, you've probably noticed something different about how this site works. Pages feel snappy. Search happens without a full reload. Tags filter seamlessly. All of this is powered by HTMX, a small JavaScript library that's transforming how we build web applications.

The Problem HTMX Solves

Traditionally, web applications required full page refreshes for almost any user interaction:

  • Clicking a link → full page reload
  • Submitting a form → new page
  • Searching → reload with results
  • Toggling a setting → page refresh

This creates a disjointed experience. The browser flickers, context is lost, and developers must build complex Single Page Application (SPA) architectures to avoid it.

The HTMX Approach

HTMX changes the fundamentals. Instead of building SPAs with complex front-end frameworks, you use attributes directly in your HTML to define interactivity.

Core idea: Any HTML element can trigger an HTTP request, and the response can replace any part of the page.

Simple Example

<!-- A button that fetches data and inserts it into the page -->
<button hx-get "/api/time" 
        hx-swap "innerHTML">
  Get current time
</button>

When clicked, HTMX fetches /api/time and replaces the button's inner HTML with the response. No JavaScript required.

How This Blog Uses HTMX

This blog demonstrates HTMX's practical value in a Django context.

Live Search

The homepage features a search input that works without page reloads:

<input type="search"
       name="q"
       placeholder="Search notes…"
       hx-get="{% url 'blog:search' %}"
       hx-trigger="keyup changed delay:300ms"
       hx-target="#post-list" />

What's happening: - User types in the search box - After 300ms of no typing, HTMX calls the blog:search view - The view returns a partial HTML template (post_cards.html) - HTMX replaces the #post-list div with the new results

Result: Instant search feedback, no full page reload, single Django query.

Why This Matters

  1. Less JavaScript — HTMX handles the AJAX, swap, and history management. You focus on the Django views and templates.

  2. Better SEO — Since the initial page loads normally, search engines see all your content. SPA frameworks often struggle with this.

  3. Faster development — No build steps for JavaScript, no state management complexity. Django templates + HTMX attributes = interactivity.

  4. Graceful degradation — If JavaScript is disabled, the page still works. All links and forms function as normal HTML.

Key HTMX Attributes

Attribute Purpose Example
hx-get Fetch content via GET hx-get "/search"
hx-post Submit form via POST hx-post "/api/submit"
hx-trigger When to fire "click changed 200ms"
hx-target Where to put response #results, this
hx-swap How to insert response innerHTML, beforeend
hx-push-url Update browser history true or false

HTMX + Django

The combination is particularly powerful:

# views.py
def search(request):
    query = request.GET.get("q", "").strip()
    posts = Post.published.filter(
        Q(title__icontains=query) | Q(summary__icontains=query)
    )
    return render(request, "blog/partials/post_cards.html", {"posts": posts})

<!-- template -->
<input hx-get="{% url 'blog:search %}"
       hx-trigger="keyup changed delay:300ms"
       hx-target="#post-list" />
<div id="post-list">{% include "blog/partials/post_cards.html" %}</div>

Flow: 1. User types → hx-trigger fires after delay 2. HTMX calls the Django view via AJAX 3. View renders a partial template 4. HTMX swaps the partial into the page 5. Browser history can be updated (hx-push-url)

Real-World Use Cases

Beyond search, HTMX enables:

  • Live previews — Markdown or rich text editing with real-time rendering
  • Toggle states — Publish/unpublish, like/unlike, dark/light mode switching
  • Pagination — "Load more" buttons that fetch the next page
  • Form validation — Real-time error messages without leaving the form
  • Confirm dialogs — AJAX-based confirmations that don't disrupt flow
  • Dynamic filters — Filter lists by category, date, author, etc.

Getting Started

  1. Add HTMX to your base template:
<script src="https://unpkg.com/htmx.org@1.9.5"></script>

Or, if you're like this project, vendor it locally.

  1. Start small — Add one hx-get attribute to an existing element.

  2. Use partials — Keep the AJAX responses as template partials (no full HTML boilerplate).

  3. Progressive enhancement — Build the static HTML first, then add HTMX attributes.

The Philosophy

HTMX isn't about replacing JavaScript frameworks entirely. It's about recognizing that most web applications don't need full SPAs. HTMX gives you the interactivity you need without the complexity you don't.

As this blog demonstrates, you can build a rich, interactive experience with just Django templates and a few HTML attributes. The result is code that's easier to understand, easier to maintain, and more resilient.

This site was built with Django 6.0+, HTMX, Tailwind CSS v4, and SQLite. All blog posts are authored in the Django admin as Markdown, rendered to HTML on save. The search, tag filtering, and pagination all use HTMX to provide a smooth experience without leaving the server-rendered flow.

Read more about the tech stack

← all notes