{"id":12325,"library":"url-search-params-polyfill","title":"URLSearchParams Polyfill","description":"This library provides a comprehensive polyfill for the native JavaScript `URLSearchParams` interface, allowing web developers to utilize its functionality in environments that lack full support, such as older browsers (e.g., IE8+) or specific Node.js versions. The current stable version is 8.2.5. The project appears to have a moderate release cadence, addressing bugs and adding features as needed, with major versions often introducing specific bug fixes or minor behavioral changes rather than massive overhauls. Key differentiators include its broad browser compatibility (down to IE8), full implementation of the MDN specification, and detection of existing `URLSearchParams` implementations to extend them rather than completely overwrite. It works seamlessly in both browser and Node.js environments, ensuring consistent behavior across different JavaScript runtimes.","status":"active","version":"8.2.5","language":"javascript","source_language":"en","source_url":"git://github.com/jerrybendy/url-search-params-polyfill","tags":["javascript","polyfill","URLSearchParams"],"install":[{"cmd":"npm install url-search-params-polyfill","lang":"bash","label":"npm"},{"cmd":"yarn add url-search-params-polyfill","lang":"bash","label":"yarn"},{"cmd":"pnpm add url-search-params-polyfill","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The polyfill extends the global `URLSearchParams` constructor; it does not export it as a named export from the module.","wrong":"import { URLSearchParams } from 'url-search-params-polyfill';","symbol":"Polyfill","correct":"import 'url-search-params-polyfill';"},{"note":"Similar to ESM, CommonJS usage also extends the global object, and does not return the `URLSearchParams` constructor from the `require` call.","wrong":"const URLSearchParams = require('url-search-params-polyfill');","symbol":"Polyfill (CommonJS)","correct":"require('url-search-params-polyfill');"},{"note":"Once the polyfill is imported, the `URLSearchParams` constructor becomes globally available or extends the existing native implementation.","wrong":"const params = new Polyfill.URLSearchParams();","symbol":"URLSearchParams Constructor","correct":"const params = new URLSearchParams();"}],"quickstart":{"code":"import 'url-search-params-polyfill'; // Ensure the polyfill is active\n\n// Instantiate URLSearchParams from various sources\nconst searchFromString = new URLSearchParams(\"id=101&from=dashboard&tags=alpha&tags=beta\");\nconsole.log('From string:', searchFromString.toString()); // id=101&from=dashboard&tags=alpha&tags=beta\n\nconst searchFromObject = new URLSearchParams({ product: 'widget', category: 'electronics' });\nsearchFromObject.append('color', 'red');\nsearchFromObject.set('category', 'home-goods');\nconsole.log('From object:', searchFromObject.toString()); // product=widget&category=home-goods&color=red\n\nconst queryParams = new URLSearchParams();\nqueryParams.append(\"user\", \"john.doe\");\nqueryParams.append(\"role\", \"admin\");\nqueryParams.set(\"status\", \"active\");\nqueryParams.append(\"tags\", \"new\");\nqueryParams.append(\"tags\", \"featured\");\n\nconsole.log(\"All 'tags' values:\", queryParams.getAll(\"tags\")); // [\"new\", \"featured\"]\nconsole.log(\"Has 'user'?\", queryParams.has(\"user\")); // true\nconsole.log(\"Query string:\", queryParams.toString()); // user=john.doe&role=admin&status=active&tags=new&tags=featured\n\nqueryParams.delete(\"role\");\nqueryParams.sort();\nconsole.log(\"Sorted query string after deleting role:\", queryParams.toString()); // status=active&tags=featured&tags=new&user=john.doe\n\nfor (const [key, value] of queryParams) {\n  console.log(`Key: ${key}, Value: ${value}`);\n}\n","lang":"typescript","description":"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`."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=8.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Adjust your code to expect `keys()` and `values()` iterators to yield raw elements directly, not single-element arrays.","message":"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`.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"all"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=8.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Attempting to use `Object.prototype` properties like `hasOwnProperty`, `toString`, etc., as search parameter names in older versions of the polyfill.","error":"TypeError: Cannot read properties of undefined (reading 'hasOwnProperty')"},{"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.","cause":"Parsing a query string that contains un-decodable `%` escape sequences with versions prior to 6.0.0.","error":"URIError: URI malformed"},{"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'`.","cause":"Using `URLSearchParams` as a `fetch` request body in browsers that support `fetch` but lack native `URLSearchParams`, without manually setting the `Content-Type` header.","error":"Request body for fetch API is not correctly interpreted as form data."}],"ecosystem":"npm"}