Serialize an HTML Form to a JavaScript Object, supporting nested attributes and arrays.
Adds the method .serializeJSON() to jQuery (or Zepto) that serializes a form into a JavaScript Object, using the same format as the default Ruby on Rails request params.
Install with bower bower install jquery.serializeJSON, or npm npm install jquery-serializejson, or just download the jquery.serializejson.js script.
And make sure it is included after jQuery (or Zepto), for example:
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="jquery.serializejson.js"></script>
HTML form (input, textarea and select tags supported):
<form id="my-profile">
<!-- simple attribute -->
<input type="text" name="fullName" value="Mario Izquierdo" />
<!-- nested attributes -->
<input type="text" name="address[city]" value="San Francisco" />
<input type="text" name="address[state][name]" value="California" />
<input type="text" name="address[state][abbr]" value="CA" />
<!-- array -->
<input type="text" name="jobbies[]" value="code" />
<input type="text" name="jobbies[]" value="climbing" />
<!-- textareas, checkboxes ... -->
<textarea name="projects[0][name]">serializeJSON</textarea>
<textarea name="projects[0][language]">javascript</textarea>
<input type="hidden" name="projects[0][popular]" value="0" />
<input type="checkbox" name="projects[0][popular]" value="1" checked />
<textarea name="projects[1][name]">tinytest.js</textarea>
<textarea name="projects[1][language]">javascript</textarea>
<input type="hidden" name="projects[1][popular]" value="0" />
<input type="checkbox" name="projects[1][popular]" value="1"/>
<!-- select -->
<select name="selectOne">
<option value="paper">Paper</option>
<option value="rock" selected>Rock</option>
<option value="scissors">Scissors</option>
</select>
<!-- select multiple options, just name it as an array[] -->
<select multiple name="selectMultiple[]">
<option value="red" selected>Red</option>
<option value="blue" selected>Blue</option>
<option value="yellow">Yellow</option>
</select>
</form>
JavaScript:
$('#my-profile').serializeJSON();
// returns =>
{
fullName: "Mario Izquierdo",
address: {
city: "San Francisco",
state: {
name: "California",
abbr: "CA"
}
},
jobbies: ["code", "climbing"],
projects: {
'0': { name: "serializeJSON", language: "javascript", popular: "1" },
'1': { name: "tinytest.js", language: "javascript", popular: "0" }
},
selectOne: "rock",
selectMultiple: ["red", "blue"]
}
The serializeJSON function returns a JavaScript object, not a JSON String. It should probably have been called serializeObject, or something like that, but those names were already taken.
To serialize into JSON, use the JSON.stringify method, that is available on all major new browsers.
To support old browsers, just include the json2.js polyfill (as described on stackoverfow).
var jsonString = JSON.stringify(obj);
Note that .serializeJSON() implememtation relies on jQuery’s .serializeArray() to grab the form attributes and then create the object using the names.
That means, it will serialize the inputs that are supported by .serializeArray(), that uses the standard W3C rules for successful controls to determine which elements it should include. In particular, the included elements cannot be disabled and must contain a name attribute. No submit button value is serialized since the form was not submitted using a button. And data from file select elements is not serialized.
Parsed values are strings by default.
But you can force values to be parsed with specific types by appending the type with a colon.
<form>
<input type="text" name="notype" value="default type is :string"/>
<input type="text" name="string:string" value=":string type overrides parsing options"/>
<input type="text" name="excluded:skip" value="Use :skip to not include this field in the result"/>
<input type="text" name="number[1]:number" value="1"/>
<input type="text" name="number[1.1]:number" value="1.1"/>
<input type="text" name="number[other stuff]:number" value="other stuff"/>
<input type="text" name="boolean[true]:boolean" value="true"/>
<input type="text" name="boolean[false]:boolean" value="false"/>
<input type="text" name="boolean[0]:boolean" value="0"/>
<input type="text" name="null[null]:null" value="null"/>
<input type="text" name="null[other stuff]:null" value="other stuff"/>
<input type="text" name="auto[string]:auto" value="text with stuff"/>
<input type="text" name="auto[0]:auto" value="0"/>
<input type="text" name="auto[1]:auto" value="1"/>
<input type="text" name="auto[true]:auto" value="true"/>
<input type="text" name="auto[false]:auto" value="false"/>
<input type="text" name="auto[null]:auto" value="null"/>
<input type="text" name="auto[list]:auto" value="[1, 2, 3]"/>
<input type="text" name="array[empty]:array" value="[]"/>
<input type="text" name="array[list]:array" value="[1, 2, 3]"/>
<input type="text" name="object[empty]:object" value="{}"/>
<input type="text" name="object[dict]:object" value='{"my": "stuff"}'/>
</form>
$('form').serializeJSON();
// returns =>
{
"notype": "default type is :string",
"string": ":string type overrides parsing options",
// :skip type removes the field from the output
"number": {
"1": 1,
"1.1": 1.1,
"other stuff": NaN, // <-- Other stuff parses as NaN (Not a Number)
},
"boolean": {
"true": true,
"false": false,
"0": false, // <-- "false", "null", "undefined", "", "0" parse as false
},
"null": {
"null": null, // <-- "false", "null", "undefined", "", "0" parse as null
"other stuff": "other stuff"
},
"auto": { // works as the parseAll option
"string": "text with stuff",
"0": 0, // <-- parsed as number
"1": 1, // <-- parsed as number
"true": true, // <-- parsed as boolean
"false": false, // <-- parsed as boolean
"null": null, // <-- parsed as null
"list": "[1, 2, 3]" // <-- array and object types are not auto-parsed
},
"array": { // <-- works using JSON.parse
"empty": [],
"not empty": [1,2,3]
},
"object": { // <-- works using JSON.parse
"empty": {},
"not empty": {"my": "stuff"}
}
}
By default (serializeJSON with no options):
This is because serializeJSON is designed to return exactly the same as a regular HTML form submission when serialized as Rack/Rails params, which ensures maximun compatibility and stability.
To change the default behavior you use the following options:
parseBooleans: true)."true" and "false" to booleans true and false."1", "33.33", "-44" to numbers like 1, 33.33, -44."null" to the null value null.:auto instead of :string.{ type: function(value){...} }{ type: function(value){...} }More info about options usage in the sections below.
In my opinion, the most confusing detail when serializing a form is the input type checkbox, that will include the value if checked, and nothing if unchecked.
To deal with this, it is a common practice to use hidden fields for the “unchecked” values:
<!-- Only one booleanAttr will be serialized, being "true" or "false" depending if the checkbox is selected or not -->
<input type="hidden" name="booleanAttr" value="false" />
<input type="checkbox" name="booleanAttr" value="true" />
This solution is somehow verbose, but it is unobtrusive and ensures progressive enhancement, because it is the standard HTML behavior (also works without JavaScript).
But, to make things easier, serializeJSON includes the option checkboxUncheckedValue and the possibility to add the attribute data-unchecked-value to the checkboxes.
For example:
<form>
<input type="checkbox" name="check1" value="true" checked/>
<input type="checkbox" name="check2" value="true"/>
<input type="checkbox" name="check3" value="true"/>
</form>
Serializes like this by default:
$('form').serializeJSON();
// returns =>
{'check1': 'true'} // Note that check2 and check3 are not included because they are not checked
Which ignores any unchecked checkboxes.
To include all checkboxes, use the checkboxUncheckedValue option like this:
$('form').serializeJSON({checkboxUncheckedValue: "false"});
// returns =>
{'check1': 'true', check2: 'false', check3: 'false'}
The “unchecked” value can also be specified via the HTML attribute data-unchecked-value (Note this attribute is only recognized by the plugin):
<form id="checkboxes">
<input type="checkbox" name="checked[bool]" value="true" data-unchecked-value="false" checked/>
<input type="checkbox" name="checked[bin]" value="1" data-unchecked-value="0" checked/>
<input type="checkbox" name="checked[cool]" value="YUP" checked/>
<input type="checkbox" name="unchecked[bool]" value="true" data-unchecked-value="false" />
<input type="checkbox" name="unchecked[bin]" value="1" data-unchecked-value="0" />
<input type="checkbox" name="unchecked[cool]" value="YUP" /> <!-- No unchecked value specified -->
</form>
Serializes like this by default:
$('form#checkboxes').serializeJSON(); // Note no option is used
// returns =>
{
'checked': {
'bool': 'true',
'bin': '1',
'cool': 'YUP'
},
'unchecked': {
'bool': 'false',
'bin': '0'
// Note that unchecked cool does not appear, because it doesn't use data-unchecked-value
}
}
You can use both the option checkboxUncheckedValue and the attribute data-unchecked-value at the same time, in which case the attribute has precedence over the option.
And remember that you can combine it with other options to parse values as well.
$('form#checkboxes').serializeJSON({checkboxUncheckedValue: 'NOPE', parseBooleans: true, parseNumbers: true});
// returns =>
{
'checked': {
'bool': true,
'bin': 1,
'cool': 'YUP'
},
'unchecked': {
'bool': false, // value from data-unchecked-value attribute, and parsed with parseBooleans
'bin': 0, // value from data-unchecked-value attribute, and parsed with parseNumbers
'cool': 'NOPE' // value from checkboxUncheckedValue option
}
}
The default type is :string, so all values are Strings by default, even if they look like booleans, numbers or nulls. For example:
<form>
<input type="text" name="bool[true]" value="true"/>
<input type="text" name="bool[false]" value="false"/>
<input type="text" name="number[0]" value="0"/>
<input type="text" name="number[1]" value="1"/>
<input type="text" name="number[2.2]" value="2.2"/>
<input type="text" name="number[-2.25]" value="-2.25"/>
<input type="text" name="null" value="null"/>
<input type="text" name="string" value="text is always string"/>
<input type="text" name="empty" value=""/>
</form>
$('form').serializeJSON();
// returns =>
{
"bool": {
"true": "true",
"false": "false",
}
"number": {
"0": "0",
"1": "1",
"2.2": "2.2",
"-2.25": "-2.25",
}
"null": "null",
"string": "text is always string",
"empty": ""
}
Note that all values are strings.
To auto-detect types, you could use the :auto type (append :auto to input name).
Or, you could use the parse options. For example, to parse nulls and numbers:
$('form').serializeJSON({parseNulls: true, parseNumbers: true});
// returns =>
{
"bool": {
"true": "true", // booleans are still strings, because parseBooleans was not set
"false": "false",
}
"number": {
"0": 0, // numbers are parsed because parseNumbers: true
"1": 1,
"2.2": 2.2,
"-2.25": -2.25,
}
"null": null, // "null" strings are converted to null becase parseNulls: true
"string": "text is always string",
"empty": ""
}
For rare cases, a custom parser can be defined with a function:
var emptyStringsAndZerosToNulls = function(val, inputName) {
if (val === "") return null; // parse empty strings as nulls
if (val === 0) return null; // parse 0 as null
return val;
}
$('form').serializeJSON({parseWithFunction: emptyStringsAndZerosToNulls, parseNumbers: true});
// returns =>
{
"bool": {
"true": "true",
"false": "false",
}
"number": {
"0": null, // <-- parsed with custom function
"1": 1,
"2.2": 2.2,
"-2.25": -2.25,
}
"null": "null",
"string": "text is always string",
"empty": null // <-- parsed with custom function
}
You can define your own types or override the defaults with the customTypes option. For example:
<form>
<input type="text" name="scary:alwaysBoo" value="not boo"/>
<input type="text" name="str:string" value="str"/>
<input type="text" name="number:number" value="5"/>
</form>
$('form').serializeJSON({
customTypes: {
alwaysBoo: function(str) { // value is always a string
return "boo";
},
string: function(str) { // all strings will now end with " override"
return str + " override";
}
}
});
// returns =>
{
"scary": "boo", // <-- parsed with type :alwaysBoo
"str": "str override", // <-- parsed with new type :string (instead of the default)
"number": 5, // <-- the default :number still works
}
The default types are defined in $.serializeJSON.defaultOptions.defaultTypes. If you want to define your own set of types, you could also re-define that option (it will not override the types, but define a new set of types).
Since serializeJSON() is called on a jQuery object, just use jQuery selectors to select only the fields you want to serialize (see Issue #28 for more info):
// Select only imputs that have a non-empty value
$('form :input[value!=""]').serializeJSON();
// Or filter them from the form
obj = $('form').find('input').not('[value=""]').serializeJSON();
// For more complicated filtering, you can use a function
obj = $form.find(':input').filter(function () {
return $.trim(this.value).length > 0
}).serializeJSON();
Using the option useIntKeysAsArrayIndex.
For example:
<form>
<input type="text" name="arr[0]" value="foo"/>
<input type="text" name="arr[1]" value="var"/>
<input type="text" name="arr[5]" value="inn"/>
</form>
Serializes like this by default:
$('form').serializeJSON();
// returns =>
{'arr': {'0': 'foo', '1': 'var', '5': 'inn' }}
Which is how the Rack parse_nested_query method behaves (remember that serializeJSON input name format is inspired by Rails parameters, that are parsed using this Rack method).
But to interpret integers as array indexes, use the option useIntKeysAsArrayIndex:
$('form').serializeJSON({useIntKeysAsArrayIndex: true});
// returns =>
{'arr': ['foo', 'var', undefined, undefined, undefined, 'inn']}
Note: that this was the default behavior of serializeJSON before version 2. Use this option for backwards compatibility.
All options defaults are defined in $.serializeJSON.defaultOptions. You can just modify it to avoid setting the option on every call to serializeJSON.
For example:
$.serializeJSON.defaultOptions.parseAll = true; // parse booleans, numbers and nulls by default
$('form').serializeJSON(); // No options => then use $.serializeJSON.defaultOptions
// returns =>
{
"bool": {
"true": true,
"false": false,
}
"number": {
"0": 0,
"1": 1,
"2.2": 2.2,
"-2.25": -2.25,
}
"null": null,
"string": "text is always string",
"empty": ""
}
I found others solving the same problem:
But none of them checked what I needed at the time serializeJSON was created. Factors that differentiate serializeJSON from most of the alternatives:
serializeArray, that creates a JavaScript array of objects, ready to be encoded as a JSON string. It takes into account the W3C rules for successful controls, making serializeJSON as standard and stable as it can be.Contributions are awesome. Feature branch pull requests are the preferred method. Just make sure to add tests for it. To run the jasmine specs, just open spec/spec_runner_jquery.html in your browser.
customTypes and inspect/override default types with the option defaultTypes. Thanks to tygriffin for the pull request.:auto type, that works like the parseAll option, but targeted to a single input.checkboxUncheckedValue). Thanks to KATT for finding and fixing the issue.checkboxUncheckedValue and attribute data-unckecked-value to allow parsing unchecked checkboxes.parseWithFunction to allow custom parsers. And fix issue #14: empty strings were parsed as a zero when parseNumbers option was true.$.serializeJSON.defaultOptions.useIntKeysAsArrayIndex = true; for backwards compatibility (see Options section). Thanks to joshuajabbour for finding the issue.Written and maintained by Mario Izquierdo