Server-Side Form Validation with Inline Errors

Welcome to the next lesson in our series on migrating from React to HTMX. So far, we've built the core "CRU" operations and, in the last session, tackled deletion with hx-delete. You're now equipped to manage the full lifecycle of data in a hypermedia-driven application.

Today, we'll address a fundamental aspect of any robust web application: form validation. Our goal is to perform server-side validation and return a form fragment with inline error messages on failure. This is a topic where the philosophical differences between a client-rendered SPA and a hypermedia system become crystal clear. Instead of fetching data and managing error states in client-side JavaScript, we'll have the server render the state directly into the HTML it sends back.

The Hypermedia Approach to Validation

In a typical React application, you might handle form validation by intercepting the submit event, making an API call, and if the API returns a 4xx error with a JSON body of validation messages, you would use useState to store those errors and conditionally render error components in your JSX.

The HTMX approach is more direct. The server is the single source of truth for validation. The flow looks like this:

1. A user submits a form.
2. The server receives the form data and validates it.
3. If validation fails, the server does not send a JSON error object. Instead, it re-renders the HTML for the form itself, but this time includes the submitted values and the corresponding error messages directly in the markup.
4. The server responds with this new HTML fragment.
5. HTMX receives the fragment and swaps it into the DOM, replacing the old form. The user sees their input preserved, along with clear, inline error messages.

This architectural difference is key. The client remains "dumb," simply swapping in whatever HTML the server provides.

The result on the client side is a seamless update, but the mechanism is entirely server-driven. The image below shows what the HTML response might look like in your browser's network tools after a failed submission.

Pattern 1: Validating the Entire Form on Submission

The simplest approach is to validate the entire form when the user clicks "Submit." If there are errors, you just send back the whole form, updated with error messages.

Here's how you'd set up the form tag:

<form hx-post="/contact" hx-swap="outerHTML">
  <!-- Form fields go here -->
  <button type="submit">Submit</button>
</form>

• hx-post="/contact": Submits the form data to the /contact endpoint.
• hx-swap="outerHTML": Instructs HTMX to replace the entire <form> element with the response from the server.

On the server, your Express handler would look something like this:

app.post('/contact', (req, res) => {
  const { name, email } = req.body;
  const errors = {};

  if (!name) {
    errors.name = 'Fullname is required';
  }
  if (!email) {
    errors.email = 'Email is required';
  }

  if (Object.keys(errors).length > 0) {
    // Validation failed. Re-render the form partial with errors and submitted values.
    // We use a 422 status code, which is semantically correct for a validation failure.
    // HTMX will process this response by default.
    return res.status(422).render('partials/contact-form', {
      errors: errors,
      values: req.body 
    });
  }

  // Validation passed. Do something with the data...
  res.send('<p>Form submitted successfully!</p>');
});

In your EJS template (partials/contact-form.ejs), you would then conditionally display the errors and pre-fill the input values:

<div class="form-group">
  <input 
    type="text" 
    name="name" 
    placeholder="Your Fullname"
    value="<%= values.name || '' %>"
    class="<%= errors.name ? 'is-invalid' : '' %>"
  >
  <% if (errors.name) { %>
    <div class="invalid-feedback"><%= errors.name %></div>
  <% } %>
</div>

This pattern is simple, robust, and ensures that validation logic is centralized on the server.

Pattern 2: Inline, Per-Field Validation

For a more dynamic user experience, you can validate individual fields as the user interacts with them (e.g., when they tab out of an input). This provides immediate feedback. The official HTMX documentation provides a great, concise example of this pattern.

This pattern isolates the validation to a specific field, preventing a full form re-render for a single field's error.

A Practical Implementation with Express & EJS

Let's look at a more detailed walkthrough that uses an Express and EJS stack, just like you're planning for your projects. The following tutorial from marcusoft.net provides an excellent, in-depth guide.

The core takeaway here is structuring your UI into logical, reusable partials that encapsulate their own validation logic. This is a powerful way to organize your server-rendered code and will feel familiar given your background in component-based architectures.

Brad Traversy also provides a very clear video demonstration of this exact pattern, which can help solidify the concept.

Advanced Techniques for a Polished UX

As a senior developer, you'll appreciate that while the basic patterns work, there are subtle UX issues to solve for a truly polished feel, such as avoiding focus loss and handling network race conditions. A fantastic video from hypermedia-tv dives deep into these production-grade solutions.

These advanced patterns—OOB swaps and hx-sync—allow you to build form validation experiences that are just as responsive and seamless as those in a top-tier SPA, but with a fraction of the client-side complexity.

Conclusion

Today we've explored one of the most important patterns in the HTMX toolkit: server-side validation. You've seen how this fundamental task is handled not by managing state on the client, but by having the server act as the single source of truth, rendering UI state directly into HTML.

Key Takeaways:

• Server-Driven UI State: Validation errors are not data to be interpreted by the client; they are part of the HTML fragment rendered by the server.
• The Re-render Pattern: The fundamental mechanism for validation failure is for the server to re-render the form partial with errors and user-submitted values.
• Inline Validation: For better UX, you can create dedicated validation endpoints for individual fields, triggered by hx-post on input elements. This often involves targeting a container div with hx-swap="outerHTML".
• Partials as Components: Structuring your forms using server-side partials (.ejs files) provides a level of organization and reusability similar to what you're used to with React components.
• Advanced Robustness: For a production-quality experience, use Out-of-Band swaps to update error messages without losing input focus, and hx-sync to prevent race conditions from rapid user input.

In our next lesson, we'll continue working with form inputs to implement live search. This will introduce you to the hx-trigger attribute and its powerful modifiers, like keyup changed delay, allowing you to finely control when requests are sent to the server.