form-fetch

AJAX fetch for HTML form submissions using form DOM data.

Installation

npm install @itrocks/form-fetch

Usage

With an HTML page containing a button, a form, and a div with id result, you can fetch your form when clicking the button:

import { formFetch } from '@itrocks/form-fetch/form-fetch.js'

document.querySelector('button').addEventListener('click', async () => 
{
	const htmlResponse = await formFetch(document.querySelector('form')).text()
	document.getElementById('result').innerHTML = htmlResponse
})

Alternatively, add a submit event listener to the form to trigger a fetch instead of a standard submission:

import { formFetchOnSubmit } from '@itrocks/form-fetch/form-fetch.js'

window.addEventListener('load', () => {
	formFetchOnSubmit(document.querySelector('form'), async response => {
		document.getElementById('result').innerHTML = await response.text()
  })
})

For a streamlined approach, use xtarget and build to automate form-fetch:

import { buildXTarget } from '@itrocks/xtarget/xtarget.js'
buildXTarget()

Features

form attributes automatically set fetch() options:

• action => fetch resource
• form data => request body
• enctype => body encoding as FormData or URLSearchParams
• method => request method

You can override these options with custom values for action and RequestInit.

API

FormElement

A type alias for form submitter elements:

type FormElement = HTMLButtonElement | HTMLFormElement | HTMLInputElement

formFetch()

Submits a form using fetch(), based on form DOM data.

response = formFetch(form)
response = formFetch(form, action)
response = formFetch(form, action, init)

Parameters:

• form: An HTMLFormElement to submit with fetch().
• action: Optional resource URL. Defaults to form's action attribute.
• init: A RequestInit object for custom request settings.
• returned response: A Promise that resolves to a Response object, as returned by the call to fetch().

Example:

document.querySelectorAll('form').forEach(form => {
	formFetch(form)
		.then(response => response.text())
		.then(html => document.getElementById('result').append(html))
})

formFetchOnSubmit()

Attaches a submit event listener to fetch instead of submit.

formFetchOnSubmit(element, setResponse)
formFetchOnSubmit(element, setResponse, init)
formFetchOnSubmit(element, setResponse, init, onError)

Parameters:

• element: A FormElement (form, button, or input). Passing a button or input allows intercepting submission without direct access to the form element.
• setResponse: A callback handling the Response:

  function(response: Response, target: string, form: HTMLFormElement): void

  • response: The retrieved Response.
  • target: The target string where the form response should be displayed, determined by the formtarget of the submitter or the target of the form.
  • form: The submitted HTMLFormElement.
    
• init: A callback that returns a RequestInit object containing any custom settings to apply to the request.
• onError: A callback that handles errors during the form submission process.

  function(error: any, action: string, target: string): void

  • error: The thrown error.
  • action: The URL of the form submission.
  • target: The target string where the form response should be displayed, determined by the formtarget of the submitter or the target of the form.

formMethod()

Determines the effective method for fetch() submit.

method = formMethod(form)
method = formMethod(form, init)

Parameters:

• form: A HTMLFormElement.
• init: An optional RequestInit object. If init.method is set, it is returned.
• returned method: The return value is the calculated HTTP method, determined by the following priority of non-empty values:
  • The value of init.method,
  • The data-method attribute value of the form,
  • The value of the form's method attribute.