hx-optimistic

An htmx extension for optimistic UI updates with automatic rollback on errors. Combine it with speculation rules (or the htmx preload extension) and the View Transitions API for truly app‑like experience with minimal JavaScript. We love JavaScript, but use it like a spice: a pinch delights, too much overwhelms.

✨ Features

- 🎯 Optimistic Updates - Immediate UI feedback while requests are processing
- 🔄 Automatic Rollback - Intelligent revert to original state on errors
- 📝 Input Interpolation - Dynamic templates with ${this.value}, ${textarea}, ${data:key} helpers
- 🎨 Template Support - Rich HTML templates for loading and error states
- ⚠️ Developer Warnings - Console warnings for unsupported patterns
- 🚫 No CSS Required - You control all styling through provided class names
- 📦 Tiny - Only 18.2KB uncompressed, 8.4KB minified, 3.0KB gzipped
- 🔧 Highly Configurable - Fine-tune behavior per element

🚀 Quick Start

$3

Via CDN (jsDelivr, pinned major):
``html


`

Alternative (unpkg, latest v1):
`html


`

Compatibility: Works with htmx 1.9+ and 2.x.

Via NPM:
`bash
npm install hx-optimistic
`

$3

Enable the extension and add optimistic behavior to any HTMX element:

`html


hx-post="/api/like"
hx-target="this"
hx-swap="outerHTML"
data-optimistic='{"values":{"textContent":"❤️ Liked!","className":"btn liked"},"errorMessage":"Failed to like"}'
>
🤍 Like


`

🎯 Core Concepts

- Use data-optimistic to declare behavior per element
- Choose between values (simple property changes) and template (full HTML)
- Automatic snapshot and revert: innerHTML, className, attributes, and dataset
- Token-based concurrency prevents stale errors from overwriting newer states
- Target resolution via hx-target or config target chains: closest, find, next, previous
- Errors via errorMessage or errorTemplate with errorMode and delay
- Interpolation supports safe patterns only; avoid arbitrary JS expressions

📦 Bundle Size

| Artifact | Size |
|---------|------|
| Unminified (hx-optimistic.js) | 18.2 KB |
| Minified (hx-optimistic.min.js) | 8.4 KB |
| Minified + gzip | 3.0 KB |

$3

Values - Perfect for simple optimistic updates:
`html
data-count="42"
data-liked="false"
hx-post="/api/like"
hx-target="this"
hx-swap="outerHTML"
data-optimistic='{
"values": {
"textContent": "❤️ Liked! (was ${data:count})",
"className": "btn liked",
"data-liked": "true"
}
}'>
🤍 Like (42)

`

Templates - Ideal for complex optimistic UI changes:
`html


data-optimistic='{
"template": "

You: ${textarea}

",
"errorTemplate": "

❌ Comment failed to post

"
}'>

Post Comment

`

$3

Dynamic content using ${...} syntax with powerful helpers:

`html


data-optimistic='{"template":"

Posting: ${textarea}

"}'>
Your comment here
Post

`

📖 Interpolation Reference

All ${...} patterns supported in templates and values:

| Pattern | Description | Example |
|---------|-------------|---------|
| ${this.value} | Element's input value | "Saving: ${this.value}" |
| ${this.textContent} | Element's text content | "Was: ${this.textContent}" |
| ${this.dataset.key} | Data attribute via dataset | "ID: ${this.dataset.userId}" |
| ${textarea} | First textarea in form | "Comment: ${textarea}" |
| ${email} | First email input | "Email: ${email}" |
| ${data:key} | Data attribute shorthand | "Count: ${data:count}" |
| ${attr:name} | Any HTML attribute | "ID: ${attr:id}" |
| ${contextKey} | Value from config.context (templates only) | "Hello, ${username}" |
| ${status} | HTTP status (errors only) | "Error ${status}" |
| ${statusText} | HTTP status text (errors only) | "Error: ${statusText}" |
| ${error} | Error message (errors only) | "Failed: ${error}" |

Form Field Helpers:
- ${textarea}, ${email}, ${password}, ${text}, ${url}, ${tel}, ${search}
- ${fieldName} - Any field with name="fieldName"

⚙️ Configuration Options

Complete configuration reference for data-optimistic:

$3


innerHTML, className, all attributes, and the element dataset are automatically captured and restored on revert; no configuration is required.

$3

`javascript
{
// Simple property updates
"values": {
"textContent": "Loading...",
"className": "btn loading"
},

// Rich HTML templates
"template": "#loading-template", // Or inline HTML
"target": "closest .card", // Different target for optimistic update
"swap": "beforeend", // Append instead of replace
"class": "my-optimistic" // Optional custom class applied during optimistic state
}
`

swap supports beforeend and afterbegin. If omitted, content is replaced.

$3


`javascript
{
"errorMessage": "Request failed",
"errorTemplate": "

Error ${status}: ${statusText}

",
"errorMode": "append", // "replace" (default) or "append"
"delay": 2000 // Auto-revert delay in ms
}
`

$3

Provide additional variables for template interpolation:

`json
{
"template": "

",
"context": { "username": "Alice" }
}
`

Full example:

`html



`

🎨 CSS Classes

This library does not include any CSS. These classes are applied so you can style them as you wish:

- hx-optimistic: applied during the optimistic update
- hx-optimistic-error: applied when an error is shown
- hx-optimistic-reverting: applied while reverting to the snapshot
- hx-optimistic-error-message: wrapper added when errorMode is "append"
- hx-optimistic-pending: may be applied to when no values/template are provided

✅ Best Practices

- Enable globally when possible: Add hx-ext="optimistic" on so elements inherit it. Use per-element hx-ext only when you need to opt-in selectively.
- Pick the right technique:
- values: simple property changes (textContent, className, data-*).
- template: richer markup; prefer a