jQuery param() Method

What You’ll Learn

$.param() turns JavaScript data into URL-encoded query strings. This tutorial covers the official signatures, plain object and array serialization, the serializeArray() input format, recursive bracket notation for nested data, the traditional shallow mode, how jQuery uses param internally for Ajax data, function return values since 1.3, jQuery 3.0 default changes, and when to prefer JSON over param strings.

Introduction

Every GET request with a query string and every POST with application/x-www-form-urlencoded body needs data encoded as key=value&key2=value2. You could concatenate strings by hand — but special characters, nested objects, and arrays get messy fast. jQuery.param() handles the encoding rules for you.

Pass a plain object like { width: 1680, height: 1050 } and get back width=1680&height=1050. Pass nested structures and jQuery walks them recursively, producing bracket notation that PHP and Ruby on Rails understand. The same function powers $.serialize() under the hood and runs automatically when you pass an object to the data option of $.ajax(), $.get(), or $.post().

Understanding jQuery.param()

jQuery.param() accepts an array, a plain object, or a jQuery object containing form input elements with name attributes. It returns a single URL-encoded string — never a parsed object. That string is ready to append after ? in a URL or to send as the body of a form-encoded POST.

Since jQuery 1.4, the default encoder is recursive: nested objects become keys like a[one], arrays become b[]. Pass true as the second argument for traditional shallow serialization that matches jQuery 1.3 behavior. Since jQuery 3.0, always pass traditional explicitly when you need it — do not rely on jQuery.ajaxSettings.traditional.

📝 Syntax

The official jQuery API accepts two signatures:

Basic form — jQuery.param( obj ) (since 1.2)

jQuery.param( obj )

Serialize obj with recursive encoding (traditional: false).

With traditional flag — jQuery.param( obj, traditional ) (since 1.4)

jQuery.param( obj, traditional )

When traditional is true, use shallow serialization — nested objects stringify as [object Object] and arrays use repeated keys without brackets.

Accepted obj types

• Plain object — { width: 1680, height: 1050 } → width=1680&height=1050
• Array of name/value pairs — the format returned by $.serializeArray(): [{ name: "first", value: "Rick" }, ...]
• jQuery collection — form inputs with name attributes; jQuery reads their current values

Function values (since 1.3)

If a property value is a function, jQuery calls it and serializes the return value, not the function itself.

Return value

• Returns a String — URL-encoded query representation. Empty input yields an empty string.
• Does not include a leading ? — append manually when building URLs.

Examples Gallery

Five progressive examples from a basic key/value object through nested recursive encoding, traditional shallow mode, form serialization, and building a GET URL for Ajax. Each links to a Try-it lab where you can edit and run the code in the browser.

var params = { width: 1680, height: 1050 };
var str = $.param( params );

$( "#results" ).text( str );
// "width=1680&height=1050"

// Human-readable for debugging
console.log( decodeURIComponent( str ) );

#results shows: width=1680&height=1050

decodeURIComponent(str) → same (no special chars to escape)

var myObject = {
  a: {
    one: 1,
    two: 2,
    three: 3
  },
  b: [ 1, 2, 3 ]
};

var encoded = $.param( myObject );
var decoded = decodeURIComponent( encoded );

$( "#encoded" ).text( encoded );
$( "#decoded" ).text( decoded );

// encoded: a%5Bone%5D=1&a%5Btwo%5D=2&a%5Bthree%5D=3&b%5B%5D=1&b%5B%5D=2&b%5B%5D=3
// decoded: a[one]=1&a[two]=2&a[three]=3&b[]=1&b[]=2&b[]=3

Encoded (URL-safe):
a%5Bone%5D=1&a%5Btwo%5D=2&a%5Bthree%5D=3&b%5B%5D=1&b%5B%5D=2&b%5B%5D=3

Decoded (readable):
a[one]=1&a[two]=2&a[three]=3&b[]=1&b[]=2&b[]=3

var myObject = {
  a: { one: 1, two: 2, three: 3 },
  b: [ 1, 2, 3 ]
};

var shallow = $.param( myObject, true );
var deep    = $.param( myObject, false );

$( "#shallow" ).text( decodeURIComponent( shallow ) );
$( "#deep" ).text( decodeURIComponent( deep ) );

// shallow decoded: a=[object Object]&b=1&b=2&b=3
// deep decoded:     a[one]=1&a[two]=2&a[three]=3&b[]=1&b[]=2&b[]=3

traditional: true → a=[object Object]&b=1&b=2&b=3

traditional: false → a[one]=1&a[two]=2&a[three]=3&b[]=1&b[]=2&b[]=3

Side-by-side comparison makes the difference obvious

// Same structure $.serializeArray() returns
var formData = [
  { name: "first",  value: "Rick" },
  { name: "last",   value: "Astley" },
  { name: "job",    value: "Rock Star" }
];

var query = $.param( formData );
$( "#query" ).text( query );
// first=Rick&last=Astley&job=Rock+Star

// Equivalent to reading a live form:
// var query = $.param( $( "#my-form" ).serializeArray() );

query = "first=Rick&last=Astley&job=Rock+Star"

Spaces encoded as + in application/x-www-form-urlencoded style

var filters = { q: "jquery param", page: 2, tags: [ "ajax", "tutorial" ] };

// Manual URL building
var baseUrl = "/api/search";
var fullUrl = baseUrl + "?" + $.param( filters );
$( "#manual-url" ).text( fullUrl );

// $.get() calls $.param() on data internally — same encoding
$.get( "/api/search", filters, function( data ) {
  console.log( "Response:", data );
} );

// Inspect what jQuery would send (beforeSend peek)
$.ajax( {
  url: "/api/search",
  data: filters,
  beforeSend: function( xhr, settings ) {
    console.log( "Serialized data:", settings.data );
  }
} );

fullUrl → /api/search?q=jquery+param&page=2&tags[]=ajax&tags[]=tutorial

$.get("/api/search", filters) appends the same param string automatically

beforeSend logs settings.data with identical encoding

🚀 Common Use Cases

• Search/filter URLs — serialize filter objects and append to the address bar for bookmarkable state.
• GET Ajax requests — pass plain objects to $.get() knowing jQuery encodes them via $.param().
• Form-encoded POST bodies — build application/x-www-form-urlencoded payloads from JavaScript objects.
• Custom form handling — collect field values manually, then $.param(array) instead of native submit.
• Debugging Ajax — log decodeURIComponent($.param(data)) before sending to verify encoding.
• Legacy backend compatibility — pass traditional: true when integrating with servers expecting pre-1.4 jQuery output.

📝 Notes

• $.param() returns a string, not an object — use it for URLs and form bodies, not for storing structured data.
• Since jQuery 1.4, default encoding is recursive — arrays use [] brackets, not repeated bare keys.
• Pass true as the second argument for traditional shallow mode — required for pre-1.4 compatibility.
• Since jQuery 3.0, traditional defaults to false — do not rely on jQuery.ajaxSettings.traditional.
• No universal param spec exists — deeply nested structures may parse differently across server languages. Prefer JSON for complex payloads.
• Function property values are called and their return values serialized (since 1.3).
• HTML5 input elements in jQuery collections are serialized since jQuery 1.4.
• $.serialize() and $.serializeArray() use $.param() internally — learn param to understand form serialization.

💡 Best Practices