Introduction
In a world dominated by complex JavaScript frameworks, HTMX offers a refreshingly simple alternative. It asks a powerful question: what if you could get the smooth, interactive user experience of a single-page application (SPA) without writing tons of JavaScript?
By 2026, HTMX has proven itself as a robust and production-ready library for developers tired of build steps, client-side state management, and API boilerplate. It embraces the original power of HTML, extending it to allow any element to make an AJAX request and swap the response directly into the DOM.
This guide will walk you through the philosophy and practical application of HTMX, showing you how to build fast, modern web applications with the simplicity of a server-rendered architecture.
The Philosophy: Hypermedia, Not JavaScript
To understand HTMX, you have to understand the problem it solves. Modern SPAs (built with React, Vue, Svelte, etc.) moved a huge amount of logic into the browser. The server provides raw data (usually JSON), and the client-side JavaScript is responsible for fetching it, managing state, and rendering HTML.
The HTMX approach is different:
- The server is responsible for rendering HTML, just like in the “old days.”
- The client (browser) makes requests to the server when the user interacts with the page.
- The server responds not with JSON, but with a small snippet of HTML.
- HTMX receives this HTML and “swaps” it into the correct place on the page.
This is called Hypermedia as the Engine of Application State (HATEOAS). The server sends not just data, but the UI itself, guiding the user’s next actions.
Getting Started: It’s Just One Script Tag
You don’t need a build step, npm, or a bundler. Just add the HTMX script to your page.
<!DOCTYPE html>
<html lang="en">
<head>
<title>HTMX Demo</title>
<script src="https://unpkg.com/[email protected]"></script>
</head>
<body>
<!-- Your content here -->
</body>
</html>
That’s it. You’re ready to use HTMX.
Your First HTMX Interaction: Click to Load
Let’s build the “Hello, World” of HTMX: a button that loads content from the server without a full page reload.
The HTML (index.html):
<h1>HTMX Demo</h1>
<button
hx-get="/load-content"
hx-target="#content-div"
hx-swap="innerHTML">
Load Content
</button>
<div id="content-div">
<!-- New content will be loaded here -->
</div>
Let’s break down those hx- attributes:
hx-get="/load-content": When this button is clicked, send aGETrequest to the/load-contentURL.hx-target="#content-div": Place the response from the server into the element with the IDcontent-div.hx-swap="innerHTML": Replace the inner HTML of the target element with the response.
The Server (e.g., a simple Express.js endpoint):
// server.js
import express from 'express';
const app = express();
app.get('/load-content', (req, res) => {
// In a real app, you might fetch this from a database.
const html = '<p>This content was loaded from the server! Time: ' + new Date().toLocaleTimeString() + '</p>';
res.send(html);
});
app.listen(3000, () => console.log('Server listening on port 3000'));
When you click the button, HTMX makes the request, gets the <p>...</p> HTML fragment back, and places it inside the #content-div. The page doesn’t reload, but it’s updated with server-rendered HTML.
Practical Examples
1. Active Search
Let’s build a search box that shows results as the user types.
The HTML:
<h3>Active Search</h3>
<input
type="search"
name="q"
placeholder="Search for a user..."
hx-post="/search"
hx-trigger="keyup changed delay:500ms"
hx-target="#search-results"
hx-indicator=".htmx-indicator">
<div id="search-results">
<!-- Results will appear here -->
</div>
<span class="htmx-indicator">Searching...</span>
New attributes:
hx-post="/search": We’ll send aPOSTrequest this time, which is common for searches that might have complex parameters.hx-trigger="keyup changed delay:500ms": This is powerful. It tells HTMX to trigger the request on thekeyupevent, but only if the value haschanged, and todelaythe request by 500ms to avoid spamming the server on every keystroke (this is called “debouncing”).hx-indicator=".htmx-indicator": While the AJAX request is in flight, HTMX will add thehtmx-requestclass to the<span>. You can use CSS to show/hide it.
The Server (Express.js):
const users = ['Alice', 'Bob', 'Charlie', 'David'];
app.post('/search', (req, res) => {
const searchTerm = (req.body.q || '').toLowerCase();
const matchingUsers = users.filter(user => user.toLowerCase().includes(searchTerm));
const html = matchingUsers.map(user => `<li>${user}</li>`).join('');
res.send(`<ul>${html}</ul>`);
});
2. Form Submission with Validation
Let’s create a contact form that shows server-side validation errors without a page refresh.
The HTML:
<form
hx-post="/contact"
hx-target="this"
hx-swap="outerHTML">
<h3>Contact Us</h3>
<div>
<label>Email</label>
<input type="email" name="email">
</div>
<div>
<label>Message</label>
<textarea name="message"></textarea>
</div>
<button type="submit">Submit</button>
</form>
hx-target="this"andhx-swap="outerHTML": This is a common pattern. It means “when the form is submitted, replace the entire form (outerHTML) with the response from the server.”
The Server (Express.js):
app.post('/contact', (req, res) => {
const { email, message } = req.body;
// --- Validation Failure ---
if (!email || !message) {
// Re-render the form with an error message
const html = `
<form hx-post="/contact" hx-target="this" hx-swap="outerHTML">
<h3 class="error">Please fill out all fields.</h3>
<div>
<label>Email</label>
<input type="email" name="email" value="${email || ''}">
</div>
<div>
<label>Message</label>
<textarea name="message">${message || ''}</textarea>
</div>
<button type="submit">Submit</button>
</form>
`;
return res.send(html);
}
// --- Validation Success ---
// In a real app, you'd save to a DB, send an email, etc.
res.send('<div>Thank you for your message!</div>');
});
If validation fails, the server sends back the same form but with error messages and the user’s input preserved. If it succeeds, it sends back a success message. The entire form is swapped in place.
3. Infinite Scroll
Load more content as the user scrolls down.
The HTML:
<h3>Posts</h3>
<div id="posts">
<!-- Initial posts rendered by the server -->
<div>Post #1</div>
<div>Post #2</div>
<div>Post #3</div>
<!-- This div will trigger the next load -->
<div hx-get="/load-posts?page=2"
hx-trigger="revealed"
hx-swap="afterend">
</div>
</div>
hx-trigger="revealed": The request is triggered as soon as this element scrolls into the viewport.hx-swap="afterend": The response from the server will be placed after this triggerdiv.
The Server (Express.js):
app.get('/load-posts', (req, res) => {
const page = parseInt(req.query.page || 1);
const next_page = page + 1;
// Generate some fake posts
let postsHtml = '';
for (let i = (page - 1) * 3 + 1; i <= page * 3; i++) {
postsHtml += `<div>Post #${i}</div>`;
}
// The response includes the new posts AND the next trigger div
const responseHtml = `
${postsHtml}
<div hx-get="/load-posts?page=${next_page}"
hx-trigger="revealed"
hx-swap="afterend">
</div>
`;
res.send(responseHtml);
});
The key is that the server’s response includes the next “trigger” div with the updated page number, creating a loop.
Conclusion
HTMX is not a replacement for JavaScript, but a powerful tool for reducing its complexity. By keeping the rendering logic on the server and using hypermedia to drive user interactions, you can build applications that are simpler, faster, and easier to maintain.
In 2026, the trend is clear: developers are rediscovering the power of the server. HTMX is at the forefront of this movement, providing a practical and elegant way to build the next generation of web applications.
Comments