Think in hypermedia

A hypermedia response contains both information and the controls for possible next actions. You do not get data alone. You get data plus the buttons and forms that make sense for that state.

A task row can show its current state and include the form that completes it:

<li id="task-42">
  <span>Send invoice</span>
  <form action="/tasks/42/complete" method="post">
    <button>Complete</button>
  </form>
</li>

After the form runs, the server returns the next representation of that row. If the task is complete, the new HTML may remove the button entirely. The client does not need a separate rule saying when that action is valid. The server decided, and the markup reflects it.

When I design an HTMX interaction, I write down four parts before touching attributes:

1. the element and event that express the user’s intent
2. the HTTP route that performs or reads the operation
3. the HTML representation returned after the operation
4. the page region that representation replaces

This keeps application state and rendering decisions on the server. It also makes responses easy to inspect. Open the Network panel and you see the exact HTML the browser was asked to use. No guessing which client template ran.

The tradeoff is more server round trips. Choose hypermedia when the server is the natural source of truth. Do not choose it when every keystroke must update a complex offline model without waiting for the network.

A common mistake is treating HTMX as a thin AJAX wrapper around JSON APIs. That misses the point. The server should return the next useful HTML, not a payload the browser still has to interpret.

Try this on your own project: take one screen you already built with a client-side state object. List what HTML each action should return and which region it replaces.