URLSearchParams inconsistent behavior with multiple same-name parameters leads to data loss on backend

[Voral]

What problem are you trying to solve?

The current implementation of URLSearchParams has a significant flaw when working with multiple parameters of the same name. Both set() and append() methods ultimately result in data loss when the URL is processed by most backend frameworks (especially PHP, some Java servlets, and others).

Current behavior:

const params = new URLSearchParams();
params.append('category', 'books');
params.append('category', 'movies');
params.append('category', 'music');
console.log(params.toString()); // "category=books&category=movies&category=music"

When this reaches a typical PHP backend:

// $_GET['category'] contains only 'music' - data loss!

The problem:

• The API suggests support for multiple values via append()
• But the string representation is incompatible with how most backend systems handle repeated parameters
• This misleads developers into thinking they can safely use multiple values
• Results in silent data loss that's hard to debug

What solutions exist today?

Currently, developers must implement manual workarounds:

// Manual grouping
const groups = {};
['books', 'movies', 'music'].forEach(value => {
    groups['category'] = groups['category'] ? groups['category'] + ',' + value : value;
});
// Then manually construct: "category=books,movies,music"

// Or use array notation manually
const params = ['books', 'movies', 'music'].map(v => `category[]=${v}`).join('&');
// "category[]=books&category[]=movies&category[]=music"

These solutions are:

• Error-prone and require extra code
• Inconsistent across different codebases
• Not discoverable for new developers

How would you solve it?

Add an optional parameter to the constructor for logical grouping:

// Current behavior (default for backward compatibility)
const params1 = new URLSearchParams(); 
// OR
const params2 = new URLSearchParams({ groupMultiple: false });

// New grouped behavior
const params3 = new URLSearchParams({ groupMultiple: true });
params3.append('category', 'books');
params3.append('category', 'movies');
console.log(params3.toString()); // "category=books,movies"

// Alternative: array notation
const params4 = new URLSearchParams({ groupMultiple: 'brackets' });
params4.append('category', 'books');
params4.append('category', 'movies');
console.log(params4.toString()); // "category[]=books&category[]=movies"

Additional methods could include:

params.getMultiple('category'); // ['books', 'movies'] - returns all values
params.toString({ groupMultiple: true }); // override default for this call

Anything else?

Why this matters:

• Prevents silent data loss in production applications
• Aligns with how form data with multiple checkboxes typically works
• Provides a migration path from current behavior
• Makes the API actually useful for real-world form handling

Backward compatibility:

• Default behavior remains unchanged (groupMultiple: false)
• New behavior is opt-in via constructor parameter
• No breaking changes for existing code

This would make URLSearchParams actually practical for handling form data with multiple selections, rather than being a footgun that looks like it supports multiple values but actually doesn't work with common backend systems.

[annevk]

Ultimately this is a flaw in the backend for not supporting application/x-www-form-urlencoded properly. If you work with such a backend it's probably better to stick with the map version of the API and not attempt to use the multi-map variant. (Or indeed follow the multi-map requirements of the backend, such as PHP requiring the [] suffix.) See also #851.

Is the functionality you suggest something that popular libraries offer? Or is this frequently asked on Stack Overflow? Or both?

[Voral]

Thank you for your response. I understand your position that the flaw may lie with the backends. However, I would like to explain why this issue is not about a theoretical specification mismatch, but rather about the most natural workflow for millions of developers.

Please accept my apologies for not noticing the similar ticket #851 you mentioned when I created this issue.

I have been working in web development since 2003, and throughout this time, the Apache/Nginx + PHP + HTML forms stack has been and remains one of the most common in the history of the internet. This is not some "incorrect" or niche configuration—it is the foundation a huge part of the web is built upon.

When I saw URLSearchParams in JavaScript, I was pleased: finally, a native, convenient tool for working with form data and query strings that could replace manual string manipulation. Specifically, the .append() method directly suggests the ability to work with multiple values, just like HTML forms with <select multiple> or groups of checkboxes do.

Here is the core problem: This tool appears to be the perfect solution for a standard task (sending form data via fetch or XMLHttpRequest), but in practice, it turns out to be a "footgun". A developer, relying on the intuitive API, unexpectedly faces silent and hard-to-debug data loss on the backend.

Regarding popular libraries—yes, all common HTTP clients (jQuery.ajax, Axios, etc.) solve this problem under the hood. They either use the PHP-style with [] or serialize arrays in their own way. The fact that these libraries had to implement their own logic on top of the native API already speaks to its inadequacy for real-world tasks.

It's worth noting that PHP adopted its array handling behavior (with [] brackets) about 20 years earlier, if I'm not mistaken. This created a de facto standard that predates the formal specification.

In essence, the current URLSearchParams creates a disconnect between:

• Expectation: "A convenient native API for working with form data."
• Reality: "A tool that works correctly only with backends that follow a pure, but less common, interpretation of the standard."

My proposal is not a demand to break backward compatibility, but an attempt to reconcile the standard with reality. Adding an optional parameter (groupMultiple or arrayFormat) would allow us to use this excellent tool for its intended purpose—seamless work with typical backends—without harming existing code.

In the end, as a developer, I've encountered a situation where a native API does not solve my everyday task, and this is disappointing. Naturally, if this functionality is not implemented, I, like many others, will simply avoid using URLSearchParams for working with multiple values and will continue to write workarounds. But I believed the goal of standards was to provide us with the very tools that save us from having to write such workarounds.

[Voral]

Of course, I understand that I can manually work around this issue by writing:

const params = new URLSearchParams();
params.append('category[]', 'books');
params.append('category[]', 'movies');

This will indeed produce the format that PHP expects: category[]=books&category[]=movies

However, this feels more like a workaround than a clean solution. It requires:

• Manually modifying parameter names with [] brackets
• Remembering which parameters should be treated as arrays
• Creating inconsistency in the API (some parameters with [], some without)

What I was hoping for is a more elegant, native way to handle this common use case. The current approach forces developers to leak backend-specific implementation details (PHP's array syntax) into their frontend JavaScript code.

A cleaner API would allow us to work logically with multi-value parameters while letting the serialization layer handle the compatibility aspects automatically.

The manual [] approach works, but it undermines the promise of URLSearchParams as a convenient, standards-based abstraction for working with query parameters and form data.

[Voral]

Although... I started thinking about the problem more deeply and remembered that PHP supports not only simple arrays with [], but also complex nested structures:

<!-- Associative arrays -->
<input name="user[name]">
<input name="user[email]">

<!-- Nested arrays with indexes -->
<input name="items[0][name]">
<input name="items[0][price]">
<input name="items[1][name]">
<input name="items[1][price]">

<!-- And even deep nesting -->
<input name="order[user][contacts][phone]">

In PHP, this parses perfectly into full-fledged data structures:

$_POST['user']['name']; // Works
$_POST['items'][0]['name']; // Works
$_POST['order']['user']['contacts']['phone']; // Works

And that's when you realize the problem is much deeper than it first appeared. We're talking not just about simple multiple values, but about an entire mechanism for serializing complex data structures in URL format.

The current URLSearchParams is not designed for such scenarios at all. Yes, I can manually write:

params.append('user[name]', 'John');
params.append('user[email]', 'test@example.com');

But this:

1. Is the same workaround, just for more complex cases
2. Is inconsistent - it forces mixing data logic with backend-specific syntactic features
3. Is hard to scale for dynamic structures

Perhaps if we're going to add support for PHP notation, we should consider a full-fledged API for working with structures, not just a flag for simple arrays. Although I understand this is much more complex and might be overkill for a native API.

I'm confused :)

[annevk]

PHP did not invent application/x-www-form-urlencoded. That format was invented when forms were added to HTML. It only has a cursory mention in HTML 3.2 though. It was slightly improved in HTML 4.01: https://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.1. And then it got a more formal definition afterwards with this specification being the current host.

And PHP is incompatible with the format. But you can use a subset of the format in a specific way as you note and it'll work fine with PHP.

We did discuss this a bit back in 2020 #556 and you are the second person to complain about it. That makes me think it's not a particularly urgent problem, but we can keep this open to gauge interest. (If more interest materializes we should probably investigate those libraries you mentioned in more detail to see what they do exactly.)

[Voral]

Yes, I understand this is not an urgent task. One way or another, everyone is solving this problem now, and it's not a complex task. On the other hand, it's quite common. And it would be nice to have a ready-made standard solution.

I thought about writing a universal wrapper for these purposes on top of URLSearchParams. I did a quick search for existing solutions. This library seems to be what I was looking for:
https://github.com/ljharb/qs

To be honest, I wouldn't have even thought about this problem if I hadn't come across a question from a beginner on one of the forums where URLSearchParams would have been very useful - if it didn't require additional learning of all these backend subtleties.

[Voral]

I apologize, I was wrong to mention Axios as a ready-made solution - it itself requires additional tools to work with PHP.

Example with Axios + qs:

import qs from 'qs';

const api = axios.create({
  paramsSerializer: params => qs.stringify(params, {arrayFormat: 'brackets'})
});

// Request with array and object
api.get('/api', {
  params: {
    categories: ['books', 'movies'],  // array
    filters: {                        // object
      price: {min: 100, max: 500},
      inStock: true
    }
  }
});
// Result: categories[]=books&categories[]=movies&filters[price][min]=100&filters[price][max]=500&filters[inStock]=true

The same example in jQuery:

$.get('/api', {
  categories: ['books', 'movies'],    // array
  filters: {                          // object
    price: {min: 100, max: 500},
    inStock: true
  }
});
// Result: categories[]=books&categories[]=movies&filters[price][min]=100&filters[price][max]=500&filters[inStock]=true

jQuery really does handle this task excellently "out of the box," which is not surprising - it's one of the most popular libraries, created during the heyday of PHP. However, in new projects, jQuery is often considered an outdated solution.