{}
Guide
Jan 15, 2024

How to POST JSON Data with HTMX

Send an HTMX POST request to your API and handle JSON responses with an official or custom HTMX 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>
html

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>
html

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>
html

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>
html

๐Ÿš›โœจ๐Ÿ’š Nice job, you successfully sent a HTTP POST request with HTMX.

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.

โœŒ๏ธ

Get notified in 5 minutes

Submit JSON delivers your submissions via email, integrations, and webhooks. Set up takes less than 5 minutes.