Skip to content
Tutorials Center
My learning

Topics

Lesson 15 of 28 ยท HTMX in Practice

Loading States, Indicators and Feedback

Show spinners with hx-indicator and the htmx-request class, animate swaps with htmx-swapping and htmx-settling, and stop race conditions with hx-sync.

A request to a server takes time, and an interface that does nothing while it waits feels broken. Users click twice, give up, or wonder whether anything happened. Good HTMX pages tell the user three things: something is loading, the content just changed, and only the latest answer counts.

HTMX supports all three with plain CSS and one attribute. While a request runs, it adds and removes CSS classes on elements. You write the styles; HTMX flips the switches. Because the classes are the whole mechanism, there is no loading-state JavaScript to write.

All examples use the in-page mock server from Setting Up. It lets a route choose its own delay with delay: 1200, which is how these demos make loading visible.

The classes HTMX manages

Four state classes

htmx-request On the requesting element (or its indicator) while the request runs.
htmx-swapping On the target between receiving the answer and swapping it.
htmx-added On new content for a moment, then removed.
htmx-settling On the target after the swap, until settling ends.

You only write CSS for them.

1 / 2

Showing an indicator

The class htmx-request is added to the element that issued the request for as long as the request is in flight. HTMX also injects a tiny stylesheet with one useful rule: an element with the class htmx-indicator is invisible (opacity: 0) until it sits inside an element, or is itself an element, that has htmx-request. So the simplest indicator is a hidden child that appears on its own:

HTML
<button hx-get="/report">
  Load report
  <img class="htmx-indicator" src="/spinner.svg" alt="">
</button>

If the indicator is somewhere else on the page, point to it with hx-indicator and any CSS selector (closest works too). HTMX then puts htmx-request on that element instead:

HTML
<button hx-get="/report" hx-indicator="#spinner">Load report</button>
<div id="spinner" class="htmx-indicator">Loadingโ€ฆ</div>

You are free to restyle things. For example, you can hide a button's label while it loads, or fade the whole target, using only the .htmx-request selector.

Spinner, button state and dimmed target

The first button carries htmx-request itself, so its label changes and its inline spinner fades in. The second button uses hx-indicator="#report", so the class moves to the report box: the box dims and its own "Loadingโ€ฆ" note appears. When the answer arrives, htmx-request disappears and everything reverts. No JavaScript is involved.

HTMX's built-in indicator rules rely on opacity. A fully transparent spinner still takes up space and can still be read by screen readers. Hide purely decorative spinners with aria-hidden="true" and announce real status messages in an aria-live="polite" region. If you prefer your own indicator CSS, set htmx.config.includeIndicatorStyles = false and write the rules yourself.

Animating swaps

Swaps happen in steps, and each step gives you a hook for a CSS transition:

  1. The response arrives. The target gets htmx-swapping, and HTMX waits for the swap delay (default 0ms, set with swap:300ms).
  2. The old content is replaced. The new elements start out with htmx-added.
  3. After the settle delay (default 20ms, set with settle:), htmx-added and htmx-settling are removed.

Because new nodes appear with htmx-added for a short moment and then lose it, a CSS transition on the removal produces a fade-in. And because the old content waits with htmx-swapping, you can fade it out first. A classic delete animation uses both ideas:

Fade rows out and in

New tasks fade in; deleted ones fade out and are then removed. The delete route returns an empty body with status 200, and outerHTML swapping an empty response removes the row.

A 204 No Content response means "do not swap anything", so it would leave the row in place. For delete-and-remove, return 200 with an empty body, or use hx-swap="delete".

Keeping focus where it was

When a swap replaces an element the user is typing in, they should not lose their cursor. HTMX handles the common case: if the focused element has an id and the new content contains an element with the same id, HTMX restores focus and the text selection after the swap. This is why the form fields in Forms, Validation and Submissions all carry ids. Without an id, HTMX has nothing reliable to match, and focus is lost.

Preventing races with hx-sync

Two requests that target the same area can finish in the wrong order. If the user clicks "Slow report" and then immediately "Fast report", the fast answer arrives first and the slow one arrives second and overwrites it. The screen now shows the answer to a question the user no longer cares about.

hx-sync coordinates requests. Its value is <selector>:<strategy>, where the selector says which element's requests to coordinate with (this by default, closest form is common) and the strategy says what to do when a second request arrives:

Strategy Behavior
drop Ignore the new request if one is already running
abort Ignore the new request if one is running; otherwise let a later request abort this one
replace Abort the running request and send the new one
queue first / queue last / queue all Wait until the current one ends, then send the first, last or every queued request

Without hx-sync, requests from the same element are queued and only the last waiting one is kept; requests from different elements are independent, which is exactly where races appear.

sequenceDiagram
    participant U as User
    participant H as HTMX
    participant S as Server
    U->>H: click Slow
    H->>S: GET /report?speed=slow
    U->>H: click Fast
    Note over H: hx-sync replace aborts Slow
    H->>S: GET /report?speed=fast
    S-->>H: Fast answer (swapped)

With replace, the earlier request is cancelled and only the newest answer is swapped.

A race, with and without hx-sync

Press the simulate button. The top group first shows the fast report and then, 800 ms later, the slow one wins, which is the wrong final state. The bottom group aborts the slow request the moment the fast one starts, so only the latest answer is ever shown.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which class does HTMX add to the requesting element while a request is in flight?

    htmx-request is present from the start of the request until the response is handled. htmx-indicator elements use it to become visible.
  2. 2. How do you make a spinner located elsewhere on the page appear during a request?

    hx-indicator names the element that receives htmx-request; the default CSS makes .htmx-indicator visible inside it.
  3. 3. A delete button's route returns 204 No Content. What happens to the row?

    HTMX never swaps 204 responses. Return 200 with an empty body, or use hx-swap="delete".
  4. 4. What does hx-sync="#panel:replace" do when a second request for #panel starts?

    replace cancels the in-flight request so only the newest request can update the page.
  5. 5. When is HTMX able to keep the cursor in an input after a swap?

    HTMX matches the focused element by id and restores focus and selection on the element with the same id.

Summary

  • HTMX toggles CSS classes: htmx-request during a request, htmx-swapping before a swap, htmx-added on new nodes and htmx-settling afterwards.
  • .htmx-indicator elements fade in when they or an ancestor carry htmx-request; hx-indicator points the class at any element.
  • swap: and settle: delays let CSS transitions fade content out and in.
  • Return 200 (not 204) when a response should remove or replace something.
  • Give inputs ids so focus survives swaps.
  • hx-sync with drop, abort, replace or queue prevents out-of-order responses.

Continue with Common Interaction Patterns.