Serialize and deserialize HTML forms
npm install form-serialization**Note: You may be able to get the functionality you need from usingFormData
(for which there are also polyfills for the browser or Node).**
Serialize form fields. A fork of
form-serialize.
- Adds deserialize
- Offers a pre-made browser bundle
- Offers ESM distribution as well as UMD
- Offers JSDoc
- Submit a form via XMLHttpRequest
- Retain settings in local storage
- Serialize to string for use within hash-based offlineable URLs
- Serialize for use within modifying history state
``shell`
npm install form-serialization
form-serialization supports two output formats, URL encoding
(the default) or a hash (JavaScript objects).
Lets serialize the following HTML form:
`html`
`js
const serialize = require('form-serialization');
const form = document.querySelector('#example-form');
const str = serialize(form);
// str -> "foo=bar"
const obj = serialize(form, {hash: true});
// obj -> { foo: 'bar' }
`
Returns a serialized form of a HTMLFormElement. Output is determined by
the serializer used. The default serializer performs URL encoding.
arg | type | desc
:--- | :--- | :---
form | HTMLForm | must be an HTMLFormElement
options | Object | optional options object
#### Options
option | type | default | desc
:--- | :--- | :---: | :---
hash | boolean | false | If true, the hash serializer will be used for serializer optiontrue
serializer | function | url-encoding | Override the default serializer (hash or url-encoding)
disabled | boolean | false | If , disabled fields will also be serializedtrue
empty | boolean | false | If , empty fields will also be serialized
Serializers take 3 arguments: result, key, value and should return a newly updated result.
See the example serializers in the index.js source file.
Only successful control
form fields are serialized (with the exception of disabled fields if disabled option
is set).
Multiselect fields with more than one value will result in an array of values
in the hash output mode using the default hash serializer
Fields who's name ends with [] are always serialized as an arrayhash
field in output mode using the default hash serializer.
The field name also gets the brackets removed from its name.
This does not affect the URL encoding mode output in any way.
`html`
`js
const serialize = require('form-serialization');
const form = document.querySelector('#example-form');
const obj = serialize(form, {hash: true});
// obj -> { foo: ['bar'] }
const str = serialize(form);
// str -> "foo[]=bar"
`
Adding numbers between brackets for the array notation above will result
in a hash serialization with explicit ordering based on the index number
regardless of element ordering.
Like the "explicit array fields" this does not
affect ULR encoding mode output in any way.
`html`
`js
const serialize = require('form-serialization');
const form = document.querySelector('#todos-form');
const obj = serialize(form, {hash: true});
// obj -> { todos: ['eggs', 'milk', 'flour'] }
const str = serialize(form);
// str -> "todos[1]=milk&todos[0]=eggs&todos[2]=flour"
`
Similar to the indexed array notation, attribute names can be added by
inserting a string value between brackets. The notation can be used to
create deep objects and mixed with the array notation.
Like the "explicit array fields" this does not
affect URL encoding mode output.
`html`
`js
const serialize = require('form-serialization');
const form = document.querySelector('#todos-form');
const obj = serialize(form, {hash: true});
// obj -> { foo: { bar: { baz: 'qux' } }, norf: [ 'item 1' ] }
``
MIT