https://github.com/what1s1ove/form-payload
Gets proper form payload – via form.elements.
https://github.com/what1s1ove/form-payload
form form-controls form-data form-handling form-values
Last synced: about 2 months ago
JSON representation
Gets proper form payload – via form.elements.
- Host: GitHub
- URL: https://github.com/what1s1ove/form-payload
- Owner: what1s1ove
- License: mit
- Created: 2021-02-26T17:27:50.000Z (about 5 years ago)
- Default Branch: main
- Last Pushed: 2025-11-05T10:45:23.000Z (4 months ago)
- Last Synced: 2025-12-17T03:34:03.045Z (3 months ago)
- Topics: form, form-controls, form-data, form-handling, form-values
- Language: JavaScript
- Homepage: https://npmjs.com/package/form-payload
- Size: 832 KB
- Stars: 8
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: readme.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# form-payload
[](https://github.com/what1s1ove/whatislove.dev/actions/workflows/ci.yml)
[](https://github.com/what1s1ove/whatislove.dev/actions/workflows/cd.yml)
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](https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement) and [form elements](https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/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](https://stackblitz.com/edit/form-payload-javascript?file=index.js)
- [TypeScript + Validation](https://stackblitz.com/edit/form-payload-typescript?file=index.ts,get-form-payload.ts)
- [React + TypeScript](https://stackblitz.com/edit/form-payload-react?file=src%2FApp.tsx)
## Usage
```html
CV:
Email:
Name:
DOB:
Submit
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);
// => 'e@mail.com'
});
generalFormNode.addEventListener('submit', (evt) => {
evt.preventDefault();
const formPayload = getFormPayload(generalFormNode);
// => { name: 'John', dob: 'Sat Mar 27 2021 02:00:00 GMT+0200' }
});
```
## Value Correspondence Table
| HTMLElement | Attributes | Included | Return Value |
| ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------- |
| [HTMLInputElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement) | [`type="text"`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/text) | ✅ | `string` |
| [HTMLInputElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement) | [`type="password"`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/password) | ✅ | `string` |
| [HTMLInputElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement) | [`type="search"`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/search) | ✅ | `string` |
| [HTMLInputElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement) | [`type="url"`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/url) | ✅ | `string` |
| [HTMLInputElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement) | [`type="tel"`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/tel) | ✅ | `string` |
| [HTMLInputElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement) | [`type="color"`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/color) | ✅ | `string` |
| [HTMLInputElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement) | [`type="radio"`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/radio) | ✅ | `string` |
| [HTMLInputElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement) | [`type="hidden"`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/hidden) | ✅ | `string` |
| [HTMLInputElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement) | [`type="email"`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/email) | ✅ | `string` |
| [HTMLInputElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement) | [`type="email"`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/email) and [`multiple`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/multiple) | ✅ | `Array` |
| [HTMLInputElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement) | [`type="number"`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/number) | ✅ | `number` |
| [HTMLInputElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement) | [`type="range"`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/range) | ✅ | `number` |
| [HTMLInputElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement) | [`type="checkbox"`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox) | ✅ | `boolean` |
| [HTMLInputElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement) | [`type="checkbox"`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox) and with `[]` in [`name`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#name) | ✅ | `Array` (See [advanced usage](#htmlinputelement-with-typecheckbox-as-array)) |
| [HTMLInputElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement) | [`type="date"`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/date) | ✅ | [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) |
| [HTMLInputElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement) | [`type="time"`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/time) | ✅ | [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) |
| [HTMLInputElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement) | [`type="month"`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/month) | ✅ | [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) |
| [HTMLInputElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement) | [`type="week"`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/week) | ✅ | [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) |
| [HTMLInputElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement) | [`type="datetime-local"`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/datetime-local) | ✅ | [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) |
| [HTMLInputElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement) | [`type="file"`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file) | ✅ | [`File`](https://developer.mozilla.org/en-US/docs/Web/API/File) or `null` |
| [HTMLInputElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement) | [`type="file"`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file) and [`multiple`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/multiple) | ✅ | Array<[File](https://developer.mozilla.org/en-US/docs/Web/API/File)> |
| [HTMLInputElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement) | [`type="button"`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/button) or [`type="submit"`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/submit) or [`type="reset"`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/reset) or [`type="image"`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/image) | ❌ | – |
| [HTMLTextAreaElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLTextareaElement) | – | ✅ | `string` |
| [HTMLSelectElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLSelectElement) | – | ✅ | `string` |
| [HTMLSelectElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLSelectElement) | [`multiple`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/multiple) | ✅ | `Array` |
| [HTMLOutputElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLOutputElement) | – | ✅ | `string` |
| [HTMLFieldsetElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLFieldsetElement) | – | ✅ | `Object` (See [advanced usage](#htmlfieldsetelement-as-object)) |
| [HTMLFieldsetElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLFieldsetElement) | with `[]` in [`name`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/fieldset#name) | ✅ | `Array>` (See [advanced usage](#htmlfieldsetelement-as-array)) |
| [HTMLButtonElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLButtonElement) | – | ❌ | – |
| [HTMLObjectElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLObjectElement) | – | ❌ | – |
## Advanced Usage
### HTMLInputElement with type="checkbox" as array
`getFormPayload` returns an array of values for checked elements when using `` with `type="checkbox"` and the `[]` symbol at the end of the `name` attribute of the `` element itself.
```html
Shop name:
Apple
Orange
Banana
Submit
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'],
// }
})
```
### HTMLFieldsetElement as object
`getFormPayload`/`getFormControlPayload` returns a nested objects when using the `` element. The key name will be based on the `name` attribute of the `` element itself. Nesting of `` elements within each other can be infinite. `getFormPayload`/`getFormControlPayload` collects all values recursively.
```html
Company name:
Shop name:
Open:
Submit
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,
// },
// }
})
```
### HTMLFieldsetElement as array
`getFormPayload`/`getFormControlPayload` returns an array of objects when using the `` element and the `[]` symbol at the end of the `name` attribute of the `` elements. The functionality of recursively collecting values from nested `` elements is preserved.
```html
Company name:
Shop name:
Open:
Shop name:
Open:
Submit
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,
// },
// ],
// }
})
```
---
Inspired by [FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData) and Web-platform in general ♡.