JavaScript URLs and Query Strings: URL and URLSearchParams

Stop Parsing URLs With String Tricks

Before the URL API existed, people sliced URLs with split('?'), regexes, and hope. It mostly worked until a value contained an &, a =, a space, or a non-ASCII character - and then it didn't. The browser and Node both ship a proper parser. Use it.

const u = new URL("https://shop.example.com/products?id=42&color=red#reviews");

console.log(u.protocol);   // "https:"
console.log(u.host);       // "shop.example.com"
console.log(u.pathname);   // "/products"
console.log(u.search);     // "?id=42&color=red"
console.log(u.hash);       // "#reviews"

One call, every part of the URL already split apart and decoded correctly. The constructor throws a TypeError on invalid input, which is usually what you want - a garbage URL should fail loudly rather than silently produce garbage downstream.

Reading Query Parameters

Every URL has a .searchParams property - a URLSearchParams object that knows how to read and write the query string:

const u = new URL("https://example.com/search?q=javascript&page=2&tag=web&tag=beginner");

console.log(u.searchParams.get("q"));        // "javascript"
console.log(u.searchParams.get("page"));     // "2"
console.log(u.searchParams.getAll("tag"));   // ["web", "beginner"]
console.log(u.searchParams.has("sort"));     // false
console.log(u.searchParams.get("sort"));     // null

A few things worth noticing:

• Values come back already decoded. ?name=Ada%20Lovelace gives you "Ada Lovelace".
• Everything is a string. "2" is not 2. Convert with Number() if you need a number.
• Repeated keys are legal. get returns the first match; getAll returns every match.
• Missing keys return null, not undefined - so ?? "default" works well with them.

Building a Query String

You can build a query string from scratch with URLSearchParams - no manual escaping, no joining with &:

const params = new URLSearchParams();
params.set("q", "hello world");
params.set("page", "2");
params.append("tag", "js");
params.append("tag", "beginner");

console.log(params.toString());
// "q=hello+world&page=2&tag=js&tag=beginner"

Or construct it from an object - any iterable of [key, value] pairs works, and a plain object does too:

const params = new URLSearchParams({
    q: "café",
    page: "1",
    sort: "new",
});

console.log(params.toString());
// "q=caf%C3%A9&page=1&sort=new"

set vs append: set replaces any existing value for that key. append adds another one. Use append when a key can legitimately repeat (tags, filters); use set for single-valued parameters.

Modifying a URL

Because URL is a live object, changing searchParams updates .search and .href automatically:

const u = new URL("https://example.com/search?q=js");

u.searchParams.set("page", "2");
u.searchParams.set("q", "typescript");     // overwrites
u.searchParams.delete("utm_source");       // no-op if absent

console.log(u.href);
// "https://example.com/search?q=typescript&page=2"

This is the idiomatic way to append a query parameter to an existing URL. No "does the URL already have a ?" check, no worrying about whether to prepend & or ?.

You can change other parts of the URL the same way:

const u = new URL("https://example.com/old");

u.pathname = "/new";
u.hash = "top";

console.log(u.href);
// "https://example.com/new#top"

Iterating Over Parameters

URLSearchParams is iterable. for...of gives you [key, value] pairs, and there are the usual keys(), values(), and entries() helpers:

const u = new URL("https://example.com/?q=js&page=2&tag=web&tag=beginner");

for (const [key, value] of u.searchParams) {
    console.log(key, "=", value);
}

Note that repeated keys show up multiple times - you'll see tag = web and then tag = beginner as separate entries. That's faithful to the actual query string.

If you want a plain object for a quick debug print, Object.fromEntries works - but it collapses repeats, keeping only the last value:

const u = new URL("https://example.com/?q=js&tag=web&tag=beginner");

const obj = Object.fromEntries(u.searchParams);
console.log(obj);   // { q: "js", tag: "beginner" }

Fine for debugging. Wrong if any key can repeat.

Relative URLs Need a Base

new URL("/search?q=js") on its own throws - a relative path isn't a valid URL by itself. Pass a base as the second argument:

const base = "https://example.com/app/";

const u1 = new URL("/search?q=js", base);
const u2 = new URL("profile", base);
const u3 = new URL("../about", base);

console.log(u1.href);   // "https://example.com/search?q=js"
console.log(u2.href);   // "https://example.com/app/profile"
console.log(u3.href);   // "https://example.com/about"

The resolution rules are the same ones browsers use for <a href>: a leading / is absolute from the host, no slash is relative to the current path, .. walks up. Very handy when you're assembling API URLs from a configured base.

In the browser, window.location.href is a ready-made base for parsing the current page's URL:

const u = new URL(window.location.href);
const page = u.searchParams.get("page") ?? "1";

Handling Invalid URLs

The URL constructor throws on malformed input. That's useful - but it means you need try/catch when parsing anything the user typed or an external system sent:

function safeParse(input) {
    try {
        return new URL(input);
    } catch {
        return null;
    }
}

console.log(safeParse("https://example.com/ok"));   // URL object
console.log(safeParse("not a url"));                // null
console.log(safeParse(""));                         // null

Modern environments also expose URL.canParse(input) - a boolean check that avoids the try/catch dance when you just want to validate:

console.log(URL.canParse("https://example.com"));   // true
console.log(URL.canParse("nope"));                  // false

A Small Working Example

Putting it together - read the current filters from a URL, tweak them, and produce a new URL to navigate to:

function updateFilters(href, changes) {
    const u = new URL(href);

    for (const [key, value] of Object.entries(changes)) {
        if (value === null) {
            u.searchParams.delete(key);
        } else {
            u.searchParams.set(key, value);
        }
    }
    return u.href;
}

const current = "https://shop.example.com/products?category=shoes&page=3&sort=price";

console.log(updateFilters(current, { page: "1", sort: null, color: "red" }));
// "https://shop.example.com/products?category=shoes&page=1&color=red"

Passing null deletes the parameter. Any other value sets or overwrites it. That's a pattern you'll end up writing in one form or another any time you build filter UIs, pagination, or deep links.

What to Take Away

• new URL(string) parses a URL into labelled parts. It throws on garbage.
• url.searchParams is a URLSearchParams - use get, getAll, set, append, delete, has.
• Encoding happens for you. Don't reach for encodeURIComponent unless you're building strings by hand.
• Pass a base URL as the second argument to resolve relative paths.
• URL.canParse (or try/catch) is your validation tool for untrusted input.

Every time you're tempted to split a URL with .split('?') or pick a query parameter out with a regex, reach for these APIs instead. They're shorter, correct, and already in the runtime.