How to POST JSON Data with HTMX

• 🌱 Solution 1: The HTMX json-enc extension
• 🧪 Solution 2: Custom HTMX JSON Extension

We recently added a bunch of new framework examples, and particularly enjoyed exploring HTMX.

An unconventional best practice with HTMX is you typically respond with HTML on the server side, not JSON.

But at Submit JSON our API conventionally uses Content-Type: application/json, so we took it upon ourselves to figure out the best way to send a HTTP request to an external API with HTMX & JSON.

We came up with two soultions that should get the job done for you:

Solution 1: HTMX json-enc Extension

This is the best option if the body of your HTTP request does not POST to a /:dynamic URL and if the request body is a flat object. Otherwise, the following Custom HTMX Extension example is what you're looking for.

First add the official json-enc extension script to your page or component:

<script src="https://unpkg.com/htmx.org/dist/ext/json-enc.js"></script>

Next, to initiate an HTMX JSON POST request, add hx-ext="json-enc" to your form alongside the hx-post attribute:

<form
  hx-target="#response" 
  hx-post="/test-form"
  hx-headers='{"X-API-KEY": "xxxxxxx"}'
  hx-ext="json-enc"
>
  <input type="text" name="name" placeholder="Name" required><br>
  <input type="email" name="email" placeholder="Email" required><br>
  <textarea name="message" placeholder="Message" required></textarea><br>
  <button type="submit">Send</button>
</form>

<div id="response"></div>

Easy peasy. This setup is perfect for sending simple JSON POST requests using HTMX.

Solution 2: Custom HTMX JSON Extension

For more nuanced control over your JSON POST requests and responses, a custom HTMX Extension is the way to go.

First use htmx.defineExtension to create a custom extension to POST a HTMX JSON request like so:

<script>
  htmx.defineExtension('submitjson', {
    onEvent: function (name, evt) {
      if (name === "htmx:configRequest") {
        evt.detail.headers['Content-Type'] = "application/json"
        evt.detail.headers['X-API-Key'] = 'sjk_xxx'
      }
    },
    encodeParameters: function(xhr, parameters, elt) {
      xhr.overrideMimeType('text/json') // override default mime type
      const body = { // set your request body
        data: parameters,
        options: { submissionFormat: 'pretty'}
      }
      return (JSON.stringify(body))
    }
  })
</script>

Once defined you can simply add the action to any DOM element with hx-yourtextension to recieve an HTMX JSON response. In our case the action is called hx-submitjson.

Here's an example integration to handle a contact us form submission notification using our API:

<form 
  hx-target="#response" 
  hx-post="https://api.submitjson.com/v1/submit/xxxxxxxx"
  hx-ext="submitjson"
>
  <input type="text" name="name" placeholder="Name" required><br>
  <input type="email" name="email" placeholder="Email" required><br>
  <textarea name="message" placeholder="Message" required></textarea><br>
  <button type="submit">Send</button>
</form>

<div id="response"></div>

For those integrating HTMX with Submit JSON, consider our JS Client for a streamlined form submission process. It pairs exceptionally well with HTMX, simplifying the handling of JSON POST requests and responses.

Also, check out the Submit JSON with HTMX Example for more context.

✌️