htmx: Extend AJAX and partial page updates with HTML attributes
A tool that lets HTML attributes drive AJAX and partial updates, with less JavaScript and no dependencies.
GitHub bigskysoftware/htmx Updated 2026-09-04 Branch master Stars 49.1K Forks 1.6K
HTML AJAX CSS Transitions WebSockets Server Sent Events JavaScript

🧭 Decision Guide

Try it if you

  • You need to declare AJAX requests and response replacement directly in HTML, such as hx-post together with hx-swap.
    The README's quick start shows hx-post, hx-swap="outerHTML", and a /clicked request.
  • Your interface needs to connect WebSockets or Server Sent Events through HTML attributes.
    The README's introduction explicitly lists WebSockets and Server Sent Events and links to the ws and sse extensions.
  • You want a dependency-free frontend tool that is about 14k min.gz'd.
    The README's introduction describes htmx as small, about 14k min.gz'd, and dependency-free.

Skip it if you

  • You plan to install the npm package named htmx instead of htmx.org.
    The README's installing as a node package section explicitly warns that htmx is an old broken package and says to use htmx.org.
  • Your selection process requires an existing formal release or a clearly documented maintenance status.
    Project metadata reports 0 releases, latest version No releases, and recent update Unknown.
  • Your compliance process must immediately identify the exact open-source license.
    Project data labels the license only as Other, and the README provides no specific license name.

Requirements

  • A browser-side CDN reference can use the README example: <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/htmx.min.js" ...></script>
  • The Node installation method is: npm install htmx.org --save
  • Local development requires installing development dependencies first; the README gives npm install.
  • For local preview, the README gives npx serve.

First step (verbatim from README)

npm install htmx.org --save

Watch out

  • Do not let npm install resolve the old htmx package; use htmx.org.
    The README's installing as a node package section explicitly calls htmx an old broken package.
  • The tests do not have an npm command entry point; the README requires starting a web server and navigating to the test page.
    The README's hacking guide says to run a web server in the root and lists /test/index.html.
  • The tests depend on mocha, chai, and sinon, with sinon used to mock AJAX requests.
    The README's hacking guide names the three testing tools and explains sinon's purpose.

Alternatives

  • intercooler.js:If existing code is already based on intercooler.js, evaluating that existing solution may reduce migration scope.
    README introduction

Not stated in the README

  • The README does not state browser compatibility or minimum browser versions.
  • The README does not specify the required server response format, error-handling conventions, or authentication method.
  • The README provides no performance benchmarks, concurrency limits, or production resource-usage data.
  • Project metadata does not provide a recent update, commit history, or maintenance signals beyond the listed contributor count.
  • The README does not identify the specific license text or commercial-use restrictions behind Other.
  • The README gives no complete test execution command; it only says to start a web server and navigate to the test page.

💡 Deep Analysis

6
Yes I need a dependency-free library of about 14KB minified and compressed, and my team manages frontend dependencies with npm. Which package should I install to avoid the broken package mentioned in the README?
For: A Node.js developer who wants to add a dependency-free, approximately 14KB frontend library to an existing server application through npm

Yes. Install htmx.org, not the similarly named htmx package.

  • The README section “installing as a node package” provides the exact command: npm install htmx.org --save.
  • The same section explicitly warns that an old broken package named htmx exists and says that the correct package is htmx.org.
  • The introduction describes htmx as approximately 14KB minified and gzip-compressed and dependency-free, matching your size and low-integration-cost constraints.
  • However, the project data lists the license as Other, and the README body does not provide the complete license terms, so the repository license files still need to be checked before redistribution.
  • installing as a node package: `npm install htmx.org --save`
  • installing as a node package: “There is an old broken package called `htmx`. This is `htmx.org`.”
  • introduction: “~14k min.gz'd” and “dependency-free”
  • Project data: license is `Other`
npm install htmx.org --save
Not stated in the README:The README does not state whether the current npm package version matches the latest release information in the project data;The complete license terms are not present in the supplied README body
Yes I plan to modify `/src/htmx.js` and add Mocha, Chai, and Sinon tests for new attribute behavior. Does the README provide clear local development and testing entry points?
For: An open-source contributor preparing to modify htmx and write attribute and regression tests with Mocha, Chai, and Sinon

Yes. The README provides a clear path from installing development dependencies to locating the relevant test areas.

  • The hacking guide says to install the development dependencies first and gives the exact command npm install.
  • It then recommends running npx serve in the repository root to start a web server for the test pages.
  • The README identifies /src/htmx.js as the place to modify when adding features and instructs contributors to add tests under the appropriate area in /test.
  • The test tree is organized into attributes, core, core/regressions.js, ext, and manual. It also explicitly names Mocha, Chai, and Sinon, with Sinon used to mock AJAX requests, matching your testing constraints.
  • hacking guide: `npm install`
  • hacking guide: `npx serve`
  • hacking guide: modify `/src/htmx.js` and add tests under `/test`
  • hacking guide: Mocha, Chai, and Sinon; test directories include attributes, core, regressions, ext, and manual
npm install
Not stated in the README:The README does not provide the exact browser URL or an automated command for running the test suite;The README does not state minimum Node.js or npm versions;The README does not say whether all tests must pass before submission
No My application depends on complex client-side state, offline capability, and highly componentized JavaScript logic. Is htmx suitable if I want to replace the current SPA state layer with it?
For: A frontend engineer maintaining an SPA with complex client state, offline capability, and heavily componentized logic

No, it is not a suitable replacement for the complete state layer of this kind of SPA; the project insight explicitly identifies complex client state and offline capability as poor fits.

  • htmx centers on HTML attributes that trigger requests and exchange server-returned HTML into the DOM, rather than maintaining complex shared state in the browser.
  • When many components share state or require complex client-side computation and fine-grained synchronization, HTML attributes can make the logic scattered and harder to reuse and maintain.
  • The project insight says complex drag-and-drop editing, heavy graphics interaction, and highly componentized client logic generally still require a fuller frontend framework or dedicated client architecture.
  • htmx may handle isolated page interactions, but the README provides no offline data synchronization or client-state management design.
  • Project insight usage_limitations: poor fit for complex client state, offline capability, complex drag-and-drop editing, heavy graphics interaction, or highly componentized client logic
  • Project insight solution_analysis: requests and DOM exchanges are configured through custom HTML attributes
  • Project insight usage_limitations: extensive cross-component shared state can make logic scattered and difficult to maintain
Not stated in the README:The README does not define integration boundaries between htmx and your current SPA framework or state-management library;The README does not describe offline caching, conflict resolution, or local-state persistence
Yes My admin system is mainly server-rendered HTML with forms and lists. I want buttons, partial refreshes, and CSS transitions to work through HTML attributes. Is htmx more suitable than introducing a full SPA framework?
For: A web developer maintaining an admin system and form-heavy server application who wants asynchronous actions through HTML attributes without adopting a full SPA framework

Yes. It is particularly suitable for admin systems and form-oriented applications with moderate interaction needs and existing server-side rendering.

  • The project insight lists admin systems, form-heavy applications, and content sites as suitable scenarios.
  • The README motivation explains that htmx removes the restrictions that only certain elements, click/submit, GET/POST, and full-screen replacement can provide interaction.
  • The quick start shows a button issuing a request through hx-post and partially replacing the response through hx-swap.
  • The introduction also lists CSS Transitions, while the runtime is approximately 14KB and dependency-free. This avoids taking on SPA-level client routing, component, and state-management costs for moderate interaction needs.
  • Project insight target_users: admin systems, form-heavy applications, and content sites
  • motivation: restrictions on which elements can make HTTP requests, which events trigger them, request methods, and full-screen replacement
  • quick start: `hx-post` and `hx-swap="outerHTML"`
  • introduction: CSS Transitions, approximately 14KB, and dependency-free
Not stated in the README:The README does not specify your server language, template engine, or existing form-validation mechanism;The README does not specify the accessibility, browser-history, or error-state requirements of your application
Yes I already use server-generated HTML and a REST/HATEOAS style, and I do not want to introduce a full SPA framework. Can htmx give me asynchronous form submission and partial DOM updates with little JavaScript?
For: A web developer maintaining server-rendered, REST/HATEOAS-style pages who wants partial refreshes for forms and lists

Yes, it fits because htmx is designed to add progressive interaction between traditional HTML and heavyweight SPA architectures.

  • The README introduction states that AJAX, CSS Transitions, WebSockets, and Server-Sent Events can be accessed directly through HTML attributes.
  • The quick start uses hx-post for the request and hx-swap="outerHTML" to replace the button with the server response, without client-side templates or a full-page reload.
  • The runtime is approximately 14KB minified and gzip-compressed and is dependency-free, which supports incremental adoption in an existing server-rendered application.
  • The server must return an HTML fragment compatible with the target DOM position. If the current API only returns JSON, an HTML rendering layer is still required.
  • introduction: “directly in HTML, using attributes”
  • quick start: `hx-post="/clicked" hx-swap="outerHTML"`
  • introduction: “~14k min.gz'd” and “dependency-free”
  • Project insight: the server must reliably generate safe and structurally correct HTML responses
Not stated in the README:The README does not say whether your current server framework already supports HTML template and fragment rendering;The README does not specify how form validation, error responses, and browser history should be handled in your application
It depends I want to add WebSocket or Server-Sent Events updates to a server-rendered HTML application. Can htmx alone solve connection management, proxy configuration, and real-time system scalability?
For: A web developer implementing real-time updates with WebSockets or Server-Sent Events who also owns server connection management and proxy deployment

It depends. htmx provides an HTML-driven way to integrate WebSockets and SSE, but it does not by itself provide the server-side reliability and scalability infrastructure for a real-time system.

  • The README introduction explicitly lists WebSockets and Server Sent Events and links to the ws and sse extension documentation.
  • The project insight says the extension mechanism can add real-time communication on demand while keeping the core library focused.
  • The same insight states that both capabilities depend on server connection management, proxy configuration, and deployment conditions; adding htmx does not solve real-time scalability or reliability.
  • If your backend already handles connection lifecycles, reconnection, broadcasting, and proxy support, htmx can serve as the page-update layer. The README does not provide the complete infrastructure design.
  • introduction: lists “WebSockets” and “Server Sent Events”
  • introduction: links to `/extensions/ws/` and `/extensions/sse/`
  • Project insight usage_limitations: depends on server connection management, proxy configuration, and deployment conditions
  • Project insight: adding htmx does not itself solve real-time scalability and reliability
Not stated in the README:The README does not identify your WebSocket or SSE server framework, proxy, or load-balancer configuration;The README does not specify reconnection, recovery, broadcasting, or connection-scale limits

✨ Highlights

  • About 14k min.gz'd and dependency-free
  • HTML attributes directly invoke AJAX, WebSockets, and SSE
  • Supports partial replacement with hx-post and hx-swap
  • Tests cover attributes, core, and regressions.js

🔧 Engineering

  • Use hx-post to issue an AJAX request from an HTML button click
  • Use hx-swap="outerHTML" to replace the target element with the response
  • Connect CSS Transitions, WebSockets, and SSE through HTML attributes

⚠️ Risks

  • The npm package must be htmx.org; the README calls htmx an old broken package
  • The README only shows a /cdn.jsdelivr.net/npm/[email protected] example
  • The license is marked Other, and the README gives no specific license name

👥 For who?

  • Frontend developers who need HTML-attribute-driven modern interfaces
  • Teams wanting hypertext-based AJAX interactions without adding dependencies