form-payload

Gets proper form payload – via form.elements.

Install

npm install form-payload

Demo

The library works perfectly with any framework. Just use a valid HTMLFormElement and form elements. If you want to add validation or any other functionality, create wrappers on top of the exported functions from the form-payload library.

• Pure JavaScript
• TypeScript + Validation
• React + TypeScript

Usage

<form name="resume">
  <label>CV: <input type="file" name="resume"></label>
</form>

<form name="mailing">
  <label>Email: <input type="email" name="mail" value="[email protected]"></label>
</form>

<form name="general">
  <label>Name: <input type="text" name="name" value="John"></label>
  <label>DOB: <input type="date" name="dob" value="2021-03-27"></label>
  <button type="submit">Submit</button>
</form>

<script>
  import { getFormPayload, getFormControlPayload } from 'form-payload';

  const {
    resume: resumeFormNode,
    mailing: mailingFormNode,
    general: generalFormNode,
  } = document.forms;

  resumeFormNode.addEventListener('change', (evt) => {
    // ❌ bad (hard to read, magic numbers, bulky, outdated approach)
    const file = evt.target.files?.[0] || null;

    // 🟡 better (modern, clear, but repetitive approach – violates DRY)
    const [file = null] = env.target.files ?? [];

    // ✅ ideal
    const file = getFormControlPayload(evt.target);
    // => File or null
  });

  mailingFormNode.addEventListener('input', (evt) => {
    const formControlPayload = getFormControlPayload(evt.target);
    // => '[email protected]'
  });

  generalFormNode.addEventListener('submit', (evt) => {
    evt.preventDefault();

    const formPayload = getFormPayload(generalFormNode);
    // => { name: 'John', dob: 'Sat Mar 27 2021 02:00:00 GMT+0200' }
  });
</script>

Value Correspondence Table

| HTMLElement | Attributes | Included | Return Value | | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------- | | HTMLInputElement | type="text" | ✅ | string | | HTMLInputElement | type="password" | ✅ | string | | HTMLInputElement | type="search" | ✅ | string | | HTMLInputElement | type="url" | ✅ | string | | HTMLInputElement | type="tel" | ✅ | string | | HTMLInputElement | type="color" | ✅ | string | | HTMLInputElement | type="radio" | ✅ | string | | HTMLInputElement | type="hidden" | ✅ | string | | HTMLInputElement | type="email" | ✅ | string | | HTMLInputElement | type="email" and multiple | ✅ | Array<string> | | HTMLInputElement | type="number" | ✅ | number | | HTMLInputElement | type="range" | ✅ | number | | HTMLInputElement | type="checkbox" | ✅ | boolean | | HTMLInputElement | type="checkbox" and with [] in name | ✅ | Array<string> (See advanced usage) | | HTMLInputElement | type="date" | ✅ | Date | | HTMLInputElement | type="time" | ✅ | Date | | HTMLInputElement | type="month" | ✅ | Date | | HTMLInputElement | type="week" | ✅ | Date | | HTMLInputElement | type="datetime-local" | ✅ | Date | | HTMLInputElement | type="file" | ✅ | File or null | | HTMLInputElement | type="file" and multiple | ✅ | Array<File> | | HTMLInputElement | type="button" or type="submit" or type="reset" or type="image" | ❌ | – | | HTMLTextAreaElement | – | ✅ | string | | HTMLSelectElement | – | ✅ | string | | HTMLSelectElement | multiple | ✅ | Array<string> | | HTMLOutputElement | – | ✅ | string | | HTMLFieldsetElement | – | ✅ | Object<name: string, value: unknown> (See advanced usage) | | HTMLFieldsetElement | with [] in name | ✅ | Array<Object<name: string, value: unknown>> (See advanced usage) | | HTMLButtonElement | – | ❌ | – | | HTMLObjectElement | – | ❌ | – |

Advanced Usage

HTMLInputElement with type="checkbox" as array

getFormPayload returns an array of values for checked elements when using <input> with type="checkbox" and the [] symbol at the end of the name attribute of the <input> element itself.

<form name="shop">
  <label>Shop name: <input name="name" type="text" value="Shop #1"></label>
  <label>Apple <input name="fruits[]" type="checkbox" value="apple" checked></label>
  <label>Orange <input name="fruits[]" type="checkbox" value="orange"></label>
  <label>Banana <input name="fruits[]" type="checkbox" value="banana" checked></label>
  <button type="submit">Submit</button>
</form>

<script>
  import { getFormPayload } from 'form-payload';

  const { shop: shopFormNode } = document.forms;

  shopFormNode.addEventListener('submit', (evt) => {
    evt.preventDefault();

    const formPayload = getFormPayload(shopFormNode);
    // =>
    // {
    //   name: 'Shop #1',
    //   fruits: ['apple', 'banana'],
    // }
  })
</script>

HTMLFieldsetElement as object

getFormPayload/getFormControlPayload returns a nested objects when using the <fieldset> element. The key name will be based on the name attribute of the <fieldset> element itself. Nesting of <fieldset> elements within each other can be infinite. getFormPayload/getFormControlPayload collects all values recursively.

<form name="company">
  <label>Company name: <input name="name" type="text" value="FreshHarvest Hub"></label>
  <fieldset name="shop">
    <label>Shop name: <input name="name" type="text" value="Shop #1"></label>
    <label>Open: <input name="isOpen" type="checkbox" checked></label>
  </fieldset>
  <button type="submit">Submit</button>
</form>

<script>
  import { getFormPayload } from 'form-payload';

  const { company: companyFormNode } = document.forms;

  companyFormNode.addEventListener('submit', (evt) => {
    evt.preventDefault();

    const formPayload = getFormPayload(companyFormNode);
    // =>
    // {
    //   name: 'FreshHarvest Hub',
    //   shop: {
    //     name: 'Shop #1',
    //     isOpen: true,
    //   },
    // }
  })
</script>

HTMLFieldsetElement as array

getFormPayload/getFormControlPayload returns an array of objects when using the <fieldset> element and the [] symbol at the end of the name attribute of the <fieldset> elements. The functionality of recursively collecting values from nested <fieldset> elements is preserved.

<form name="company">
  <label>Company name: <input name="name" type="text" value="FreshHarvest Hub"></label>
  <fieldset name="shops[]">
    <label>Shop name: <input name="name" type="text" value="Shop #1"></label>
    <label>Open: <input name="isOpen" type="checkbox" checked></label>
  </fieldset>
  <fieldset name="shops[]">
    <label>Shop name: <input name="name" type="text" value="Shop #2"></label>
    <label>Open: <input name="isOpen" type="checkbox"></label>
  </fieldset>
  <button type="submit">Submit</button>
</form>

<script>
  import { getFormPayload } from 'form-payload';

  const { company: companyFormNode } = document.forms;

  companyFormNode.addEventListener('submit', (evt) => {
    evt.preventDefault();

    const formPayload = getFormPayload(companyFormNode);
    // =>
    // {
    //   name: 'FreshHarvest Hub',
    //   shops: [
    //     {
    //       name: 'Shop #1',
    //       isOpen: true,
    //     },
    //     {
    //       name: 'Shop #2',
    //       isOpen: false,
    //     },
    //   ],
    // }
  })
</script>

Inspired by FormData and Web-platform in general ♡.