Folders and files

<scripttype="text/javascript"src="jquery.js"></script><scripttype="text/javascript"src="jquery.serializejson.js"></script>

<form><inputtype="text"name="title"value="Dune"/><inputtype="text"name="author[name]"value="Frank Herbert"/><inputtype="text"name="author[period]"value="1945–1986"/></form>

$('form').serializeJSON();// returns =>{title:"Dune",author:{name:"Frank Herbert",period:"1945–1986"}}

<formid="my-profile"><!-- simple attribute --><inputtype="text"name="name"value="Mario"/><!-- nested attributes --><inputtype="text"name="address[city]"value="San Francisco"/><inputtype="text"name="address[state][name]"value="California"/><inputtype="text"name="address[state][abbr]"value="CA"/><!-- array --><inputtype="text"name="jobbies[]"value="code"/><inputtype="text"name="jobbies[]"value="climbing"/><!-- nested arrays, textareas, checkboxes ... --><textareaname="projects[0][name]">serializeJSON</textarea><textareaname="projects[0][language]">javascript</textarea><inputtype="hidden"name="projects[0][popular]"value="0"/><inputtype="checkbox"name="projects[0][popular]"value="1"checked/><textareaname="projects[1][name]">tinytest.js</textarea><textareaname="projects[1][language]">javascript</textarea><inputtype="hidden"name="projects[1][popular]"value="0"/><inputtype="checkbox"name="projects[1][popular]"value="1"/><!-- select --><selectname="selectOne"><optionvalue="paper">Paper</option><optionvalue="rock"selected>Rock</option><optionvalue="scissors">Scissors</option></select><!-- select multiple options, just name it as an array[] --><selectmultiplename="selectMultiple[]"><optionvalue="red"selected>Red</option><optionvalue="blue"selected>Blue</option><optionvalue="yellow">Yellow</option></select></form>

$('#my-profile').serializeJSON();// returns =>{fullName:"Mario",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"]}

TheserializeJSON function returns a JavaScript object, not a JSON String. The plugin should probably have been calledserializeObject or similar, but that plugin name was already taken.

To convert into a JSON String, use theJSON.stringify method, that is available on all majornew browsers.If you need to support very old browsers, just include thejson2.js polyfill (as described onstackoverfow).

varobj=$('form').serializeJSON();varjsonString=JSON.stringify(obj);

The plugin serializes the same inputs supported by.serializeArray(), following the standard W3C rules forsuccessful controls. In particular, the included elementscannot be disabled and must contain aname 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.

Fields values are:string by default. But can be parsed with types by appending a:type suffix to the field name:

<form><inputtype="text"name="default"value=":string is default"/><inputtype="text"name="text:string"value="some text string"/><inputtype="text"name="excluded:skip"value="ignored field because of type :skip"/><inputtype="text"name="numbers[1]:number"value="1"/><inputtype="text"name="numbers[1.1]:number"value="1.1"/><inputtype="text"name="numbers[other]:number"value="other"/><inputtype="text"name="bools[true]:boolean"value="true"/><inputtype="text"name="bools[false]:boolean"value="false"/><inputtype="text"name="bools[0]:boolean"value="0"/><inputtype="text"name="nulls[null]:null"value="null"/><inputtype="text"name="nulls[other]:null"value="other"/><inputtype="text"name="arrays[empty]:array"value="[]"/><inputtype="text"name="arrays[list]:array"value="[1, 2, 3]"/><inputtype="text"name="objects[empty]:object"value="{}"/><inputtype="text"name="objects[dict]:object"value='{"my": "stuff"}'/></form>

$('form').serializeJSON();// returns =>{"default":":string is the default","text":"some text string",// excluded:skip is ignored in the output"numbers":{"1":1,"1.1":1.1,"other":NaN,// <-- "other" is parsed as NaN},"bools":{"true":true,"false":false,"0":false,// <-- "false", "null", "undefined", "", "0" are parsed as false},"nulls":{"null":null,// <-- "false", "null", "undefined", "", "0"  are parsed as null"other":"other"// <-- if not null, the type is a string},"arrays":{// <-- uses JSON.parse"empty":[],"not empty":[1,2,3]},"objects":{// <-- uses JSON.parse"empty":{},"not empty":{"my":"stuff"}}}

Types can also be specified with the attributedata-value-type, instead of adding the:type suffix in the field name:

<form><inputtype="text"name="anumb"data-value-type="number"value="1"/><inputtype="text"name="abool"data-value-type="boolean"value="true"/><inputtype="text"name="anull"data-value-type="null"value="null"/><inputtype="text"name="anarray"data-value-type="array"value="[1, 2, 3]"/></form>

If your field names contain colons (e.g.name="article[my::key][active]") the last part after the colon will be confused as an invalid type. One way to avoid that is to explicitly append the type:string (e.g.name="article[my::key][active]:string"), or to use the attributedata-value-type="string". Data attributes have precedence over:type name suffixes. It is also possible to disable parsing:type suffixes with the option{ disableColonTypes: true }.

Use thecustomTypes option to provide your own parsing functions. The parsing functions receive the input name as a string, and the DOM elment of the serialized input.

<form><inputtype="text"name="scary:alwaysBoo"value="not boo"/><inputtype="text"name="str:string"value="str"/><inputtype="text"name="five:number"value="5"/></form>

$('form').serializeJSON({customTypes:{alwaysBoo:(strVal,el)=>{// strVal: is the input value as a string// el: is the dom element. $(el) would be the jQuery elementreturn"boo";// value returned in the serialization of this type},}});// returns =>{"scary":"boo",// <-- parsed with custom type "alwaysBoo""str":"str","five":5,}

The providedcustomTypes can include one of thedetaultTypes to override the default behavior:

$('form').serializeJSON({customTypes:{alwaysBoo:(strVal)=>{return"boo";},string:(strVal)=>{returnstrVal+"-OVERDRIVE";},}});// returns =>{"scary":"boo",// <-- parsed with custom type "alwaysBoo""str":"str-OVERDRIVE",// <-- parsed with custom override "string""five":5,// <-- parsed with default type "number"}

Default types used by the plugin are defined in$.serializeJSON.defaultOptions.defaultTypes.

With no options,.serializeJSON() returns the same as a regular HTML form submission when serialized as Rack/Rails params. In particular:

• Values arestrings (unless appending a:type to the input name)
• Unchecked checkboxes are ignored (as defined in the W3C rules forsuccessful controls).
• Disabled elements are ignored (W3C rules)
• Keys (input names) are alwaysstrings (nested params are objects by default)

Available options:

• checkboxUncheckedValue: string, return this value on checkboxes that are not checked. Without this option, they would be ignored. For example:{checkboxUncheckedValue: ""} returns an empty string. If the field has a:type, the returned value will be properly parsed; for example if the field type is:boolean, it returnsfalse instead of an empty string.
• useIntKeysAsArrayIndex: true, when using integers as keys (i.e.<input name="foods[0]" value="banana">), serialize as an array ({"foods": ["banana"]}) instead of an object ({"foods": {"0": "banana"}).
• skipFalsyValuesForFields: [], skip given fields (by name) with falsy values. You can usedata-skip-falsy="true" input attribute as well. Falsy values are determined after converting to a given type, note that"0" as:string (default) is still truthy, but0 as:number is falsy.
• skipFalsyValuesForTypes: [], skip given fields (by :type) with falsy values (i.e.skipFalsyValuesForTypes: ["string", "number"] would skip"" for:string fields, and0 for:number fields).
• customTypes: {}, define your own:type functions. Defined as an object like{ type: function(value){...} }. For example:{customTypes: {nullable: function(str){ return str || null; }}. Custom types extend defaultTypes.
• defaultTypes: {defaults}, contains the orignal type functionsstring,number,boolean,null,array,object andskip.
• defaultType: "string", fields that have no:type suffix and nodata-value-type attribute are parsed with thestring type function by default, but it could be changed to use a different type function instead.
• disableColonTypes: true, do not parse input names as types, allowing field names to use colons. If this option is used, types can still be specified with thedata-value-type attribute. For example<input name="foo::bar" value="1" data-value-type="number"> will be parsed as a number.

More details about these options in the sections below.

One of the most confusing details when serializing a form is the input type checkbox, because it includes the value if checked, but nothing if unchecked.

To deal with this, a common practice in HTML forms is 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 --><inputtype="hidden"name="booleanAttr"value="false"/><inputtype="checkbox"name="booleanAttr"value="true"/>

This solution is somehow verbose, but ensures progressive enhancement, it works even when JavaScript is disabled.

But, to make things easier,serializeJSON includes the optioncheckboxUncheckedValue and the possibility to add the attributedata-unchecked-value to the checkboxes:

<form><inputtype="checkbox"name="check1"value="true"checked/><inputtype="checkbox"name="check2"value="true"/><inputtype="checkbox"name="check3"value="true"/></form>

Serializes like this by default:

$('form').serializeJSON();// returns =>{check1:'true'}// check2 and check3 are ignored

To include all checkboxes, use thecheckboxUncheckedValue option:

$('form').serializeJSON({checkboxUncheckedValue:"false"});// returns =>{check1:"true",check2:"false",check3:"false"}

Thedata-unchecked-value HTML attribute can be used to targed specific values per field:

<formid="checkboxes"><inputtype="checkbox"name="checked[b]:boolean"value="true"data-unchecked-value="false"checked/><inputtype="checkbox"name="checked[numb]"value="1"data-unchecked-value="0"checked/><inputtype="checkbox"name="checked[cool]"value="YUP"checked/><inputtype="checkbox"name="unchecked[b]:boolean"value="true"data-unchecked-value="false"/><inputtype="checkbox"name="unchecked[numb]"value="1"data-unchecked-value="0"/><inputtype="checkbox"name="unchecked[cool]"value="YUP"/><!-- No unchecked value specified --></form>

$('form#checkboxes').serializeJSON();// No option is needed if the data attribute is used// returns =>{'checked':{'b':true,'numb':'1','cool':'YUP'},'unchecked':{'bool':false,'bin':'0'// 'cool' is not included, because it doesn't use data-unchecked-value}}

You can use both the optioncheckboxUncheckedValue and the attributedata-unchecked-value at the same time, in which case the option is used as default value (the data attribute has precedence).

$('form#checkboxes').serializeJSON({checkboxUncheckedValue:'NOPE'});// returns =>{'checked':{'b':true,'numb':'1','cool':'YUP'},'unchecked':{'bool':false,// value from data-unchecked-value attribute, and parsed with type "boolean"'bin':'0',// value from data-unchecked-value attribute'cool':'NOPE'// value from checkboxUncheckedValue option}}

You can use the option.serializeJSON({skipFalsyValuesForTypes: ["string"]}), which ignores any string field with an empty value (default type is :string, and empty strings are falsy).

Another option, sinceserializeJSON() is called on a jQuery object, is to just use the proper jQuery selector to skip empty values (seeIssue #28 for more info):

// Select only imputs that have a non-empty value$('form :input[value!=""]').serializeJSON();// Or filter them from the formobj=$('form').find('input').not('[value=""]').serializeJSON();// For more complicated filtering, you can use a functionobj=$form.find(':input').filter(function(){return$.trim(this.value).length>0}).serializeJSON();

When using :types, you can also skip falsy values (false, "", 0, null, undefined, NaN) by using the optionskipFalsyValuesForFields: ["fullName", "address[city]"] orskipFalsyValuesForTypes: ["string", "null"].

Or setting a data attributedata-skip-falsy="true" on the inputs that should be ignored. Note thatdata-skip-falsy is aware of field :types, so it knows how to skip a non-empty input like this<input name="foo" value="0" data-value-type="number" data-skip-falsy="true"> (Note that"0" as a string is not falsy, but0 as number is falsy)).

By default, all serialized keys arestrings, this includes keys that look like numbers like this:

<form><inputtype="text"name="arr[0]"value="foo"/><inputtype="text"name="arr[1]"value="var"/><inputtype="text"name="arr[5]"value="inn"/></form>

$('form').serializeJSON();// arr is an object =>{'arr':{'0':'foo','1':'var','5':'inn'}}

Which is how Rackparse_nested_query behaves. Remember that serializeJSON input name format is fully compatible with Rails parameters, that are parsed using this Rack method.

Use the optionuseIntKeysAsArrayIndex to interpret integers as array indexes:

$('form').serializeJSON({useIntKeysAsArrayIndex:true});// arr is an array =>{'arr':['foo','var',undefined,undefined,undefined,'inn']}

Note: this was the default behavior of serializeJSON before version 2. You can 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 toserializeJSON. For example:

$.serializeJSON.defaultOptions.checkboxUncheckedValue="";// include unckecked checkboxes as empty strings$.serializeJSON.defaultOptions.customTypes.foo=(str)=>{returnstr+"-foo";};// define global custom type ":foo"

Other plugins solve the same problem in similar ways:

• https://github.com/macek/jquery-serialize-object
• https://github.com/hongymagic/jQuery.serializeObject
• https://github.com/danheberden/jquery-serializeForm
• https://github.com/maxatwork/form2js (plain js, no jQuery)
• https://github.com/serbanghita/formToObject.js (plain js, no jQuery)
• https://gist.github.com/shiawuen/2634143 (simpler but small)

None of them did what I needed at the timeserializeJSON was created. Factors that differentiateserializeJSON from the alternatives:

• Simple and small code base. The minimified version is < 1Kb.
• Yet flexible enough with features like nested objects, unchecked-checkboxes and custom types.
• Implementation follows the same rules as the jQuery methodserializeArray, that creates a JavaScript array of objects, ready to be encoded as a JSON string. Taking into account the W3C rules forsuccessful controls for better compatibility.
• The format for the input field names is the same used by Rails (fromRack::Utils.parse_nested_query), that is successfully used by many backend systems and already well understood by many front end developers.
• Exaustive test suite helps iterate on new releases and bugfixes with confidence.
• Compatible withbower,zepto.js and pretty much every version ofjQuery.

Contributions are awesome. Feature branchpull requests are the preferred method. Just make sure to add tests for it. To run the jasmine specs, just openspec/spec_runner_jquery.html in your browser.

SeeCHANGELOG.md

Written and maintained byMario Izquierdo