URLSearchParams Polyfill

Common errors

• TypeError: Cannot read properties of undefined (reading 'hasOwnProperty')

  cause Attempting to use `Object.prototype` properties like `hasOwnProperty`, `toString`, etc., as search parameter names in older versions of the polyfill.
  fix Upgrade `url-search-params-polyfill` to version 8.0.0 or higher. This version specifically addresses and fixes the bug allowing these property names to be used.

• URIError: URI malformed

  cause Parsing a query string that contains un-decodable `%` escape sequences with versions prior to 6.0.0.
  fix Update `url-search-params-polyfill` to version 6.0.0 or newer. This version includes a fix to handle such malformed URI components gracefully without throwing an error.

• Request body for fetch API is not correctly interpreted as form data.

  cause Using `URLSearchParams` as a `fetch` request body in browsers that support `fetch` but lack native `URLSearchParams`, without manually setting the `Content-Type` header.
  fix When creating a `fetch` request with a `URLSearchParams` body, explicitly set the `Content-Type` header to `'application/x-www-form-urlencoded; charset=UTF-8'`.

Warnings

• breaking Version 8.0.0 fixed a serious bug where `Object.prototype` properties (e.g., `hasOwnProperty`) could not be used as search parameter names and would cause an error. If your application inadvertently or intentionally used such names, this update changes behavior to correctly handle them.
  Fix: Ensure your code does not rely on the previous error behavior for parameter names. Update to version 8.0.0 or later to use `Object.prototype` properties as parameter names without error.
• breaking Version 6.0.0 changed the behavior of decoding query strings containing special characters. Previously, if a query string had an un-decodable `%` character, it would fail to parse and throw an error. This version fixes the issue, leading to different parsing results for malformed URIs.
  Fix: Update to version 6.0.0 or later to correctly parse query strings with un-decodable `%` characters. Review any code that might have relied on the previous error-throwing behavior for such inputs.
• breaking Version 4.0.0 updated the prototypes of `keys()` and `values()` methods. They no longer wrap individual elements in their own arrays. This is a breaking change if your iteration logic or data processing relied on `keys()` or `values()` returning `[element]` instead of `element`.
  Fix: Adjust your code to expect `keys()` and `values()` iterators to yield raw elements directly, not single-element arrays.
• gotcha When using `URLSearchParams` objects with the `fetch` API in browsers that support `fetch` but lack native `URLSearchParams` support (e.g., Edge 14-16, Chrome 40-48), the `Content-Type: application/x-www-form-urlencoded; charset=UTF-8` header is not automatically added. This can lead to incorrect request bodies.
  Fix: Manually add the `Content-Type: application/x-www-form-urlencoded; charset=UTF-8` header to your `fetch` requests when the `body` is an instance of `URLSearchParams` to ensure compatibility across all environments.
• gotcha React Native has a native `URLSearchParams` implementation that is a no-op, meaning it exists but performs no actions. Version 8.1.0 changed how the polyfill detects and handles existing `URLSearchParams` support, which might alter behavior in React Native environments compared to prior versions.
  Fix: If working with React Native, test thoroughly after updating to 8.1.0 or later to ensure the polyfill behaves as expected and provides the necessary `URLSearchParams` functionality, as the detection mechanism was modified.

Install

• npm install url-search-params-polyfill npm
• yarn add url-search-params-polyfill yarn
• pnpm add url-search-params-polyfill pnpm

Imports

• Polyfill
  wrong:

  import { URLSearchParams } from 'url-search-params-polyfill';

  correct:

  import 'url-search-params-polyfill';

  The polyfill extends the global `URLSearchParams` constructor; it does not export it as a named export from the module.
• Polyfill (CommonJS)
  wrong:

  const URLSearchParams = require('url-search-params-polyfill');

  correct:

  require('url-search-params-polyfill');

  Similar to ESM, CommonJS usage also extends the global object, and does not return the `URLSearchParams` constructor from the `require` call.
• URLSearchParams Constructor
  wrong:

  const params = new Polyfill.URLSearchParams();

  correct:

  const params = new URLSearchParams();

  Once the polyfill is imported, the `URLSearchParams` constructor becomes globally available or extends the existing native implementation.

Quickstart

Demonstrates how to import the `URLSearchParams` polyfill and use various `URLSearchParams` methods like instantiation from strings or objects, `append`, `set`, `get`, `getAll`, `has`, `delete`, `sort`, and iteration using `for...of`.

import 'url-search-params-polyfill'; // Ensure the polyfill is active

// Instantiate URLSearchParams from various sources
const searchFromString = new URLSearchParams("id=101&from=dashboard&tags=alpha&tags=beta");
console.log('From string:', searchFromString.toString()); // id=101&from=dashboard&tags=alpha&tags=beta

const searchFromObject = new URLSearchParams({ product: 'widget', category: 'electronics' });
searchFromObject.append('color', 'red');
searchFromObject.set('category', 'home-goods');
console.log('From object:', searchFromObject.toString()); // product=widget&category=home-goods&color=red

const queryParams = new URLSearchParams();
queryParams.append("user", "john.doe");
queryParams.append("role", "admin");
queryParams.set("status", "active");
queryParams.append("tags", "new");
queryParams.append("tags", "featured");

console.log("All 'tags' values:", queryParams.getAll("tags")); // ["new", "featured"]
console.log("Has 'user'?", queryParams.has("user")); // true
console.log("Query string:", queryParams.toString()); // user=john.doe&role=admin&status=active&tags=new&tags=featured

queryParams.delete("role");
queryParams.sort();
console.log("Sorted query string after deleting role:", queryParams.toString()); // status=active&tags=featured&tags=new&user=john.doe

for (const [key, value] of queryParams) {
  console.log(`Key: ${key}, Value: ${value}`);
}