Requests and responses
Return the updated HTML
Let the server render the changed state and return the exact fragment the target needs.
8 minute lesson
Return the representation the target needs after the server has decided the new state.
For a task list target, a successful create can return the complete list:
<ul id="task-list">
<li>Send invoice</li>
<li>Book train</li>
</ul>
Returning only the new row is smaller, but returning the full list also keeps sorting, totals, empty states, and permissions consistent. Choose the smallest fragment that contains the complete changed state.
Validation is also HTML. If a form targets itself with outerHTML, return the form with safe values and field-specific messages:
<form id="new-task" action="/tasks" method="post" hx-post="/tasks"
hx-target="this" hx-swap="outerHTML">
<p class="error">Enter a title.</p>
<!-- labeled controls with the safe submitted values -->
</form>
Render the fragment through the same server templates used by full pages. Do not duplicate escaping and presentation rules in client JavaScript.
Test the endpoint directly. Its response should be valid in the target’s HTML context and should never expose private fields merely because only part of the page is returned.
Lesson completed