URLSearchParams basics

In the last lesson, you saw that every URL object has a searchParams property. Now it’s time to understand what that property actually gives you. URLSearchParams is JavaScript’s built-in tool for reading and writing query strings, the ?key=value&other=thing part of a URL.

You could parse query strings manually by splitting on ?, then &, then =, then dealing with encoding. That’s a headache. URLSearchParams does all of it for you.

What are search params?

Search parameters (also called query parameters) are the key-value pairs that appear after the ? in a URL. They’re how you send data through a URL.

For example, in this URL:

https://shop.com/search?category=shoes&color=red

There are two parameters: category with the value "shoes", and color with the value "red".

Four ways to create URLSearchParams

From a string

const params = new URLSearchParams("category=shoes&color=red");

You pass the raw query string directly. The leading ? is optional. Both "?category=shoes" and "category=shoes" work fine.

From an object (most common)

const params = new URLSearchParams({
  category: "shoes",
  color: "red",
  size: "10",
});

This is the cleanest way when you know your parameters upfront. Each key in the object becomes a parameter name, and each value becomes the parameter value.

From a URL object

const url = new URL("https://shop.com/search?category=shoes");
const params = url.searchParams;

This gives you a live URLSearchParams that’s connected to the URL. We’ll cover what “live” means later in this section. For now, just know that changes to params will update the URL automatically.

From an array of pairs

const params = new URLSearchParams([
  ["tag", "javascript"],
  ["tag", "tutorial"],
]);

Each inner array is a [key, value] pair. This is the only way to create URLSearchParams with duplicate keys from the start. Notice that "tag" appears twice. That’s allowed, and sometimes it’s exactly what you need.

Reading values: get() and getAll()

get(key) returns the first value

const params = new URLSearchParams("name=Alice&age=30&hobby=coding&hobby=reading");

params.get("name"); // "Alice"
params.get("age"); // "30"        ← always a string!
params.get("hobby"); // "coding"    ← only the FIRST one
params.get("missing"); // null        ← key doesn't exist

Let’s walk through each call. params.get("name") looks for the key "name" and returns its value, "Alice". params.get("age") returns "30", not the number 30. That’s an important detail: query string values are always strings.

What about "hobby"? There are two entries for that key: coding and reading. But get() only returns the first one. If you need all of them, you need a different method.

And if the key doesn’t exist at all? You get null. Not undefined, not an empty string. null.

getAll(key) returns all values as an array

params.getAll("hobby"); // ["coding", "reading"]  ← both values!
params.getAll("name"); // ["Alice"]               ← array with one item
params.getAll("nope"); // []                      ← empty array (not null!)

getAll() always returns an array. If the key has multiple values, you get all of them. If it has one value, you get an array with one item. And if the key doesn’t exist, you get an empty array [], not null.

That difference from get() is worth remembering. get("nope") returns null. getAll("nope") returns []. They handle missing keys differently.

Checking existence: has()

Sometimes you just want to know whether a parameter exists, without reading its value:

const params = new URLSearchParams("name=Alice&[email protected]");

params.has("name"); // true
params.has("email"); // true
params.has("phone"); // false

You can also check for a specific key and value combination:

const params = new URLSearchParams("color=red&color=blue");

params.has("color"); // true
params.has("color", "red"); // true
params.has("color", "green"); // false

The two-argument version asks: “Does this key exist with this specific value?” This is useful when a key has multiple values and you want to check for a particular one.

Counting parameters: size

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

params.size; // 3

size counts entries, not unique keys. The key "a" appears twice, so the total is 3, not 2. This is the same behavior as a Map.

A note about duplicate keys

URLs are allowed to have the same key multiple times. This is common in the real world:

/search?tag=javascript&tag=typescript&tag=react

This is why getAll() exists, so you can retrieve all three values. And it’s why get() only returns the first one: it’s designed for the common case where each key appears once.

If you’re building an API that accepts filters, tags, or any multi-select input, duplicate keys are something you’ll see regularly. In the next lesson, we’ll learn how to add, change, and remove parameters.