URLSearchParams: Browser Support, Methods, Known Issues

What is URLSearchParams?

URLSearchParams is a built-in JavaScript interface defined by the WHATWG URL Standard. It provides utility methods to read, edit, append, and delete the key-value pairs in the query string of a URL. The interface is iterable, so the entries also work in for...of loops and the spread operator.

Which browsers does URLSearchParams support?

URLSearchParams works in every modern browser. Chrome, Firefox, Safari, Edge, Opera, and Samsung Internet all ship it by default, while Internet Explorer never added support.

What are the key methods of URLSearchParams?

URLSearchParams ships twelve instance methods plus a size property. They cover reading, writing, iterating, and serializing the key-value pairs of a query string.

• append(name, value): Adds a new key-value pair at the end without removing duplicates.
• delete(name): Removes every entry that matches the given key.
• get(name): Returns the first value tied to a key, or null if the key is missing.
• getAll(name): Returns every value tied to a key as a string array.
• has(name): Returns true if any entry with the key exists.
• set(name, value): Replaces every existing entry that matches the key with one new value.
• sort(): Reorders all entries alphabetically by key, in stable order.
• toString(): Returns the serialized query string, ready to drop into a URL.
• entries(), keys(), values(): Return iterators over the entries, keys, or values of the params.
• forEach(callback): Runs a callback for every entry, in insertion order.
• size: A read-only number that counts entries. Available in Chrome 113+, Edge 113+, Firefox 116+, Opera 99+, and Safari 17+.

What are the common use cases of URLSearchParams?

Developers reach for URLSearchParams whenever a URL carries data. The most common patterns are reading filters from the address bar, building a clean query string for fetch, and updating the URL without a full page reload.

• Reading query parameters from window.location.search: Pass window.location.search straight into the constructor to parse all current params with no manual splitting.
• Building POST request bodies for fetch: Pair URLSearchParams with fetch to send application/x-www-form-urlencoded data, with no manual encoder needed.
• Updating the URL with history.replaceState: Mutate a URLSearchParams object and call history.replaceState to keep the new state in the address bar without a navigation.
• Working with the URL constructor: Every URL object exposes a live searchParams property; assign through it to mutate the underlying URL in one place.
• Sharing filter state across users: Encode dashboard filters into a query string so users can copy a link that reproduces the same view.
• Iterating params in a loop: A for...of loop over the URLSearchParams object yields each [key, value] pair in insertion order.

How do you check if a browser supports URLSearchParams?

Run a single feature check in JavaScript or use the DevTools console. The interface is exposed as a global, so a typeof check confirms support in seconds.

• Open DevTools: Press F12 or right-click the page and choose Inspect, then switch to the Console tab.
• Check the global: Type typeof URLSearchParams and press Enter. If the console logs the string function, the browser supports the interface.
• Confirm a method works: Run new URLSearchParams("a=1&b=2").get("a"). A return value of 1 confirms the constructor and get method both work.
• Test the size property: Run new URLSearchParams("a=1&b=2").size. A return value of 2 confirms the modern size property; undefined means the browser is older than Chrome 113, Firefox 116, or Safari 17.
• Save a reusable snippet: Paste the feature-detection block below into the console so you can run the same check on every browser in your support matrix.

Paste this snippet into the browser DevTools console to confirm URLSearchParams support and the newer size property:

// Run in any browser DevTools console.
const supportsUSP = typeof URLSearchParams === "function";
const supportsSize = supportsUSP && "size" in new URLSearchParams();

console.log("URLSearchParams supported:", supportsUSP);
console.log("URLSearchParams.size supported:", supportsSize);

if (supportsUSP) {
    const params = new URLSearchParams("q=test&page=2");
    console.log("q value:", params.get("q"));
    console.log("entry count:", supportsSize ? params.size : [...params].length);
} else {
    console.log("Load a polyfill before parsing query strings.");
}

If supportsUSP logs false, the page should load a polyfill before any code calls new URLSearchParams. If supportsSize logs false, count entries with Array.from(params).length instead of params.size.

What are the known issues with URLSearchParams?

URLSearchParams has solid support across modern browsers, but a few real edge cases still trip up production code. The biggest hits are Internet Explorer, the plus-sign decoding rule, and the late-arriving size property.

• Internet Explorer never added it: IE 5.5 to 11 do not provide URLSearchParams. Use core-js or url-search-params-polyfill for any IE traffic, or migrate users to Edge.
• The plus sign is decoded as a space: URLSearchParams follows the application/x-www-form-urlencoded rule, so a literal + in the query becomes a space when read back. To send a literal plus, encode it as %2B before building the URL.
• The size property is recent: URLSearchParams.size ships from Chrome 113, Edge 113, Firefox 116, Opera 99, and Safari 17. On older browsers, count entries with Array.from(params).length or [...params].length.
• iOS Safari 10.3 plus-sign bug: Early Safari iOS 10.3 builds parsed + differently from spec, encoding it twice on round-trips through URLSearchParams.toString. Modern iOS 15+ is fully compliant.
• No support for nested objects or arrays: URLSearchParams flattens every value to a string, so a nested object coerces to [object Object]. Serialize complex state with JSON.stringify before passing it to the constructor.
• new URLSearchParams(undefined) differs across runtimes: Older Node.js builds threw a TypeError on this call, while browsers always returned an empty params object. Pass an explicit empty string for predictable behavior across runtimes.
• Axios sends URLSearchParams as a JSON body in old Safari 13: Safari 13 had a known fetch and XHR bug where a URLSearchParams body was serialized incorrectly. Build the form body with new FormData or set the Content-Type header by hand on those targets.

In my experience, the most common bug is the plus sign showing up as a space. A user search for c++ tutorials arrives at the server as c tutorials, and the team spends an afternoon hunting before realizing the form should encode + as %2B before building the URLSearchParams object.

Citations

All URLSearchParams version numbers and platform notes in this guide come from these primary sources:

• MDN Web Docs - URLSearchParams: developer.mozilla.org/en-US/docs/Web/API/URLSearchParams
• MDN Web Docs - URLSearchParams() constructor: developer.mozilla.org/en-US/docs/Web/API/URLSearchParams/URLSearchParams
• MDN Web Docs - URLSearchParams.size: developer.mozilla.org/en-US/docs/Web/API/URLSearchParams/size
• MDN Web Docs - URL.searchParams: developer.mozilla.org/en-US/docs/Web/API/URL/searchParams
• WHATWG URL Standard - URLSearchParams class: url.spec.whatwg.org/#interface-urlsearchparams
• Wikipedia - URL: en.wikipedia.org/wiki/URL
• Chrome for Developers - Easy URL manipulation with URLSearchParams: developer.chrome.com/blog/urlsearchparams
• Apple Developer - URLSearchParams: developer.apple.com/documentation/webkitjs/urlsearchparams
• WebKit blog: webkit.org/blog
• Mozilla Hacks - Firefox release notes: hacks.mozilla.org/category/firefox
• Microsoft Learn - Microsoft Edge documentation: learn.microsoft.com/en-us/microsoft-edge
• Node.js - URL documentation: nodejs.org/api/url.html