htmx-universal-patterns

Original：🇺🇸 English

Translated

The definitive guide for building Hypermedia-Driven Applications (HDA) using HTMX, prioritizing security and UX patterns.

1installs

Added on2026-02-08

NPX Install

npx skill4agent add ecelayes/roots-skills htmx-universal-patterns

HTML over JSON: The server MUST respond with HTML fragments (partials), not JSON.
Side Effects via HTML: Do not use client-side logic to update the DOM. Let the server response dictate changes via
```
hx-swap
```
.

CSRF Protection: HTMX requests are non-idempotent (POST/PUT/DELETE) and require CSRF protection just like standard forms.
- Header Method: Configure the global
```
hx-headers
```
  to include the token:
```
<body hx-headers='{"X-CSRF-Token": "{{ csrfToken }}"}'>
```
  .
- Form Method: If headers aren't viable, ensure every
```
<form>
```
  includes the hidden CSRF input.
XSS Prevention: Since we are injecting HTML, ensure all user content rendered on the server is strictly escaped before reaching the client.

The "Partial" Rule: Identify strictly which part of the UI needs updating. Create a server route that renders only that component.
Idempotency: GET requests should never change state. Use POST/PUT/PATCH/DELETE for actions.
Progressive Enhancement: Design the feature to work with standard HTML forms/links first where possible.

Request Indicators: ALWAYS use

hx-indicator

.

Pattern:

<button hx-post="..." hx-indicator="#loading-spinner">Save</button>

Active States: Use the
```
htmx-added
```
class or
```
hx-vals
```
to manage active states via server rendering.

The backend must communicate status via HTTP Codes:

200 OK: Swap content normally.
204 No Content: Do nothing.
422 Unprocessable Entity: Validation error. Swap the form with the HTML containing error messages.
HX-Retarget: Use this header if an error requires updating a global element (like a top-level alert) instead of the local target.