Modifying search params

Now that you can read parameters, let’s learn how to add, change, and remove them. This is where URLSearchParams really earns its keep. But there’s one distinction you need to get right from the start, because getting it wrong causes subtle bugs that are hard to track down.

set() vs append(): the critical difference

These two methods look similar but behave very differently. Let’s take them one at a time.

set(key, value) replaces everything for a key

set() says: “I want exactly this value for this key. Remove any existing values.”

const params = new URLSearchParams();

params.set("color", "red");
console.log(params.toString()); // "color=red"

params.set("color", "blue"); // REPLACES "red"
console.log(params.toString()); // "color=blue"

The first set() creates a new entry with the key "color" and the value "red". The second set() finds that the key "color" already exists, removes it, and creates a new entry with "blue". The old value is gone.

If the key already exists multiple times, set() removes all existing entries for that key and creates a single new one.

append(key, value) adds alongside existing values

append() says: “Add another value for this key. Keep everything that’s already there.”

const params = new URLSearchParams();

params.append("size", "M");
params.append("size", "L"); // BOTH exist now
console.log(params.toString()); // "size=M&size=L"

The first append() creates size=M. The second append() doesn’t replace anything. It adds a second entry, size=L, right alongside the first one. Both values coexist under the same key.

Seeing them side by side

This is the clearest way to understand the difference:

// set() = "I want EXACTLY this value for this key"
const a = new URLSearchParams();
a.set("x", "1");
a.set("x", "2");
a.set("x", "3");
console.log(a.toString()); // "x=3"           ← only the last one

// append() = "I want to ADD another value for this key"
const b = new URLSearchParams();
b.append("x", "1");
b.append("x", "2");
b.append("x", "3");
console.log(b.toString()); // "x=1&x=2&x=3"  ← all three

With set(), each call replaces the previous value, so you end up with only "3". With append(), each call adds a new entry, so you end up with all three.

When to use which?

• set() for most cases. When each key should have exactly one value: a page number, a sort order, a user ID.
• append() when a key can have multiple values: tags, categories, selected checkboxes.

If you’re ever unsure, ask yourself: “Should this key have one value or many?” That tells you which method to use.

delete(key): removing parameters

const params = new URLSearchParams("a=1&b=2&c=3&b=4");

params.delete("b");
console.log(params.toString()); // "a=1&c=3"

delete() removes all values for the given key. Both b=2 and b=4 are gone in one call.

You can also delete a specific key-value combination:

const params = new URLSearchParams("tag=js&tag=css&tag=html");

params.delete("tag", "css"); // only removes tag=css
console.log(params.toString()); // "tag=js&tag=html"

The two-argument version is surgical. It removes only the entry that matches both the key and the value.

sort(): alphabetical ordering

sort() reorders all parameters alphabetically by key name:

const params = new URLSearchParams("z=last&a=first&m=middle");

params.sort();
console.log(params.toString());
// "a=first&m=middle&z=last"

Why would you ever sort parameters? Cache keys. If your app caches API responses by URL, you want ?a=1&b=2 and ?b=2&a=1 to hit the same cache entry. Sorting ensures consistent key order so the same query always produces the same string. This is exactly how production apps handle URL-based caching.

toString(): getting the string back

toString() converts the URLSearchParams back to a query string:

const params = new URLSearchParams({ name: "Alice", age: "30" });
console.log(params.toString());
// "name=Alice&age=30"

Quick reference

Now you can read, add, modify, and remove parameters. But what if you need to loop through all of them? That’s what the next lesson covers.