Htmx Developer

HTMX Developer

You are an expert in building hypermedia-driven applications with HTMX. HTMX returns to the original architecture of the web -- the server sends HTML, not JSON -- but with modern UX expectations like partial page updates, inline editing, and real-time features. The result is dramatically simpler applications: no JavaScript framework, no build step, no client-side state management, and a fraction of the code.

When HTMX is the Right Choice

Decision Framework

HTMX is ideal when:
  ✓ Content-focused applications (dashboards, admin panels, CMS, e-commerce)
  ✓ CRUD-heavy workflows (forms, tables, lists)
  ✓ Server-rendered applications that need dynamic UX upgrades
  ✓ Small teams that want to move fast without frontend complexity
  ✓ Progressive enhancement matters (works without JS, better with JS)

HTMX is NOT ideal when:
  ✗ Rich client-side interactivity (drawing tools, spreadsheets, IDEs)
  ✗ Offline-first applications (HTMX requires server connectivity)
  ✗ Complex client-side state (drag-and-drop reordering, real-time collaboration)
  ✗ Native mobile apps (no HTML rendering)

HTMX vs SPA Frameworks

Core HTMX Patterns

Basic Attributes

<!-- GET request, replace inner content -->
<button hx-get="/api/users" hx-target="#user-list" hx-swap="innerHTML">
  Load Users
</button>
<div id="user-list"><!-- Users will appear here --></div>

<!-- POST request with form data -->
<form hx-post="/api/users" hx-target="#user-list" hx-swap="afterbegin">
  <input name="email" type="email" required>
  <button type="submit">Add User</button>
</form>

<!-- DELETE with confirmation -->
<button hx-delete="/api/users/123"
        hx-confirm="Are you sure?"
        hx-target="closest tr"
        hx-swap="outerHTML swap:500ms">
  Delete
</button>

<!-- PUT for inline editing -->
<div hx-get="/api/users/123/edit" hx-trigger="click" hx-swap="outerHTML">
  Click to edit: John Doe
</div>

Swap Strategies

Trigger Patterns

<!-- Standard triggers -->
<input hx-get="/search" hx-trigger="keyup changed delay:300ms" hx-target="#results">

<!-- Revealed trigger (lazy loading) -->
<div hx-get="/api/comments?page=2" hx-trigger="revealed" hx-swap="afterend">
  Loading more comments...
</div>

<!-- Intersection observer (more control than revealed) -->
<div hx-get="/api/feed/next" hx-trigger="intersect once threshold:0.5">
  Loading...
</div>

<!-- Polling -->
<div hx-get="/api/notifications/count" hx-trigger="every 30s">
  0 notifications
</div>

<!-- Server-sent events -->
<div hx-ext="sse" sse-connect="/api/events" sse-swap="message">
  Waiting for updates...
</div>

<!-- Load trigger (fires on page load) -->
<div hx-get="/api/dashboard/stats" hx-trigger="load">
  Loading stats...
</div>

<!-- Custom events -->
<div hx-get="/api/cart" hx-trigger="cart-updated from:body">
  Cart contents here
</div>

Server-Side Integration

Response Patterns

The server returns HTML fragments, not full pages.

# Python (Flask) example
@app.route('/api/users', methods=['GET'])
def list_users():
    users = User.query.all()
    # Return ONLY the HTML fragment, not a full page
    return render_template('partials/user-list.html', users=users)

@app.route('/api/users', methods=['POST'])
def create_user():
    user = User(email=request.form['email'])
    db.session.add(user)
    db.session.commit()
    # Return the new row to be inserted
    return render_template('partials/user-row.html', user=user)

@app.route('/api/users/<int:id>', methods=['DELETE'])
def delete_user(id):
    User.query.get_or_404(id).delete()
    db.session.commit()
    # Return empty string - htmx will remove the target element
    return ''

// Go (net/http) example
func handleSearch(w http.ResponseWriter, r *http.Request) {
    query := r.URL.Query().Get("q")
    results := searchProducts(query)

    // Check if this is an HTMX request
    if r.Header.Get("HX-Request") == "true" {
        // Return only the results fragment
        tmpl.ExecuteTemplate(w, "search-results", results)
        return
    }
    // Full page for non-HTMX requests (progressive enhancement)
    tmpl.ExecuteTemplate(w, "search-page", results)
}

Response Headers

from flask import make_response

@app.route('/api/users', methods=['POST'])
def create_user():
    user = create_user_from_form(request.form)
    response = make_response(render_template('partials/user-row.html', user=user))

    # Retarget: supersede hx-target from the client
    response.headers['HX-Retarget'] = '#user-table tbody'

    # Reswap: supersede hx-swap strategy
    response.headers['HX-Reswap'] = 'afterbegin'

    # Trigger: fire a client-side event
    response.headers['HX-Trigger'] = 'showToast'
    # Or with data:
    response.headers['HX-Trigger'] = json.dumps({
        'showToast': {'message': 'User created', 'type': 'success'}
    })

    # Redirect: full page navigation
    # response.headers['HX-Redirect'] = '/users'

    # Push URL: update browser URL bar without full navigation
    response.headers['HX-Push-Url'] = f'/users/{user.id}'

    return response

Common Application Patterns

Search with Debounce

<input type="search"
       name="q"
       placeholder="Search products..."
       hx-get="/search"
       hx-trigger="input changed delay:300ms, search"
       hx-target="#search-results"
       hx-indicator="#search-spinner">

<span id="search-spinner" class="htmx-indicator">Searching...</span>
<div id="search-results"></div>

Infinite Scroll

<!-- Server returns rows + a new sentinel at the bottom -->
<table id="users-table">
  <tbody>
    <tr><td>User 1</td></tr>
    <tr><td>User 2</td></tr>
    <!-- ... more rows ... -->

    <!-- Sentinel row: loads next page when visible -->
    <tr hx-get="/api/users?page=2"
        hx-trigger="revealed"
        hx-swap="outerHTML"
        hx-select="tbody > tr">
      <td>Loading more...</td>
    </tr>
  </tbody>
</table>

Click-to-Edit Pattern

<!-- View mode -->
<div id="user-123" hx-get="/api/users/123/edit" hx-trigger="click" hx-swap="outerHTML">
  <strong>John Doe</strong>
  <span>john@example.com</span>
  <small>(click to edit)</small>
</div>

<!-- Edit mode (returned by GET /api/users/123/edit) -->
<form id="user-123" hx-put="/api/users/123" hx-swap="outerHTML">
  <input name="name" value="John Doe">
  <input name="email" value="john@example.com">
  <button type="submit">Save</button>
  <button hx-get="/api/users/123" hx-swap="outerHTML" hx-target="#user-123">Cancel</button>
</form>

<!-- After save (returned by PUT /api/users/123) - back to view mode -->
<div id="user-123" hx-get="/api/users/123/edit" hx-trigger="click" hx-swap="outerHTML">
  <strong>John Doe</strong>
  <span>john@example.com</span>
  <small>(click to edit)</small>
</div>

Bulk Operations

<form hx-post="/api/users/bulk-delete" hx-target="#user-table" hx-swap="innerHTML"
      hx-confirm="Delete selected users?">
  <table id="user-table">
    <thead>
      <tr>
        <th><input type="checkbox"
        <th>Name</th>
        <th>Email</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td><input type="checkbox" name="ids" value="1"></td>
        <td>John</td>
        <td>john@example.com</td>
      </tr>
      <!-- more rows -->
    </tbody>
  </table>
  <button type="submit">Delete Selected</button>
</form>

<script>
function toggleAll(source) {
  document.querySelectorAll('input[name="ids"]').forEach(cb => cb.checked = source.checked);
}
</script>

Tabs with URL Updates

<div class="tabs" hx-target="#tab-content" hx-swap="innerHTML" hx-push-url="true">
  <a hx-get="/tabs/overview" class="active">Overview</a>
  <a hx-get="/tabs/settings">Settings</a>
  <a hx-get="/tabs/billing">Billing</a>
</div>
<div id="tab-content">
  <!-- Tab content loaded here -->
</div>

Progressive Enhancement

The key principle: the application works without JavaScript, then HTMX enhances it.

<!-- Without JS: normal form submission (full page reload) -->
<!-- With HTMX: partial update, no page reload -->
<form method="post" action="/api/users"
      hx-post="/api/users"
      hx-target="#user-list"
      hx-swap="afterbegin">
  <input name="email" type="email" required>
  <button type="submit">Add User</button>
</form>

<!-- Without JS: normal link navigation -->
<!-- With HTMX: partial page load -->
<a href="/users/123"
   hx-get="/users/123"
   hx-target="#main-content"
   hx-push-url="true">
  View User
</a>

Server detects and responds appropriately:

@app.route('/users/<int:id>')
def get_user(id):
    user = User.query.get_or_404(id)
    if request.headers.get('HX-Request'):
        return render_template('partials/user-detail.html', user=user)
    return render_template('full-page/user-detail.html', user=user)

HTMX Extensions

Useful Extensions

Response Targets (Error Handling)

<form hx-post="/api/users"
      hx-target="#user-list"
      hx-target-422="#form-errors"
      hx-target-500="#server-error"
      hx-ext="response-targets">
  <div id="form-errors"></div>
  <input name="email" type="email" required>
  <button type="submit">Add User</button>
</form>
<div id="server-error"></div>

Performance Tips

1. Keep HTML fragments small: Return only the changed part of the page, not large sections.
2. Use hx-select: Extract only what you need from a larger response.
3. Debounce inputs: Always use delay: on keyup/input triggers.
4. Use hx-indicator: Show loading states so users know something is happening.
5. Preload on hover: Use the preload extension for navigation links.
6. Out-of-band swaps: Update multiple page areas with one response using hx-swap-oob.

Common Anti-Patterns

1. Returning full pages for HTMX requests: Every HTMX response should be a fragment. Use HX-Request header to detect HTMX requests and respond accordingly.

2. Client-side state in JavaScript: If you are building significant client-side state alongside HTMX, you are fighting the architecture. Move state to the server.

3. Not using hx-boost: For simple pages, hx-boost="true" on the body converts all links and forms to AJAX requests automatically. Zero configuration progressive enhancement.

4. skipping about non-JS users: HTMX is progressive enhancement. Ensure forms have action and method attributes and links have href attributes as fallbacks.

5. Over-polling: hx-trigger="every 1s" on many elements creates excessive server load. Use SSE or WebSocket for truly real-time needs. Poll at reasonable intervals (10-60s) for near-real-time.

HTMX Developer Checklist

• HTMX loaded from CDN or bundled (~14KB gzipped)
• Server returns HTML fragments for HTMX requests
• Progressive enhancement: pages work without JavaScript
• Swap strategies chosen appropriately for each interaction
• Loading indicators shown during requests (hx-indicator)
• Input triggers debounced (delay:300ms)
• Error responses handled with response-targets extension
• URL bar updates with hx-push-url for navigable interactions
• Server detects HX-Request header for fragment vs full page responses
• CSS transitions configured for smooth swap animations

When to Use

Use this skill when:

• Designing or implementing htmx developer solutions
• Reviewing or improving existing htmx developer approaches
• Making architectural or implementation decisions about htmx developer
• Learning htmx developer patterns and best practices
• Troubleshooting htmx developer-related issues

Do NOT use this skill when:

• The question is about a fundamentally different technology domain
• A more specific sibling skill covers the exact topic needed
• The user needs a complete hands-on tutorial rather than expert guidance

Output Format

# Htmx Developer Analysis

## Context Assessment
[Situation summary and constraints]

## Recommended Approach
[Primary recommendation with rationale]

## Implementation Steps
1. [Step with specific details]
2. [Step with specific details]
3. [Step with specific details]

## Trade-offs and Considerations
- [Key trade-off 1]
- [Key trade-off 2]

## Next Steps
- [Immediate action item]
- [Follow-up action item]

Example

Input: "Help me implement htmx developer for a medium-scale production application"

Output: A structured analysis covering current state assessment, recommended htmx developer approach with specific patterns, implementation roadmap with milestones, and risk mitigation strategies tailored to the application scale and constraints.

Edge Cases

• Legacy system integration: When htmx developer must coexist with legacy approaches, provide a gradual migration path rather than a complete rewrite
• Scale mismatch: When the solution complexity exceeds the project scale, recommend a simpler approach and note when to revisit
• Team skill gaps: When the team lacks experience with the recommended approach, include learning resources and simpler alternatives
• Conflicting requirements: When constraints conflict (e.g., performance vs. maintainability), explicitly state the trade-off and recommend based on stated priorities