URL & URLSearchParams

A URL is an address with parts

A URL is the address of a page or file on the web, like https://example.com/docs?q=url. It looks like one piece of text. But it is made of parts:

• The protocol, like https:, says how to fetch the page.
• The host, like example.com, names the computer (the server) that has the page.
• The port, like :8443, is a door number on that computer. Most URLs leave it out.
• The path, like /docs/url, says which page on that computer.
• The query string, like ?q=url, carries extra data as name=value pairs.
• The hash, like #examples, points to one spot inside the page.

JavaScript has two built-in tools for these parts:

• URL reads a whole address and splits it into its parts.
• URLSearchParams reads and changes the query string, the part after ?.

Why not just join strings with +? Joining works for plain words. It breaks when the text has special characters. Say a user searches for rock & roll. In a URL, & means "a new pair starts here". So the search gets cut in two. Browsers and Node.js already know all the URL rules. These two tools use those rules for you.

If strings are still new to you, keep the Strings and Unicode and strings lessons open. This lesson also turns query pairs into an object. The Object.keys, values and entries lesson explains how that works.

To parse text means to read it and split it into its parts. new URL() parses an address. You can call it in two ways:

• new URL(input) needs a full address that starts with a protocol, like https://example.com/docs. A full address is called an absolute URL.
• new URL(input, base) also takes a short address, like ../search. A short address is called a relative URL. JavaScript works out the full address from the base, the full address you pass second.

If the input is not a valid URL, new URL() stops and throws a TypeError. It does not guess.

The new URL object has one property for each part. It also tidies some parts, so the same address always looks the same:

• href is the whole address.
• origin is the protocol, host, and port together, like https://example.com:8443. It answers "which site is this?"
• port is an empty string, "", when the URL uses the usual port for its protocol. For https:, the usual port is 443.
• hostname writes a name with non-English letters, like mañana.example, in plain letters, digits, and dashes that start with xn--. This form is called punycode.
• hash keeps its #. Only the browser uses the hash. It is not sent to the server.

const url = new URL("https://example.com:8443/docs/page?tab=api#examples");
console.log(url.protocol);
console.log(url.host);
console.log(url.pathname);
console.log(url.search);
console.log(url.hash);
console.log(url.origin);

Line 1 parses one absolute URL. Lines 2 to 7 print six of its parts:

• Line 2 prints the protocol, https:.
• Line 3 prints the host, example.com:8443. host includes the port. hostname would leave the port out.
• Line 4 prints the path, /docs/page.
• Line 5 prints the query string, ?tab=api. It keeps its ?.
• Line 6 prints the hash, #examples.
• Line 7 prints the origin, https://example.com:8443.

const base = "https://example.com/docs/guides/";
const url = new URL("../search?q=rock", base);
console.log(url.href);

The base ends in /guides/. The input ../search means "go up one folder, then find search". So JavaScript leaves guides/ and stays in /docs/. Line 3 prints https://example.com/docs/search?q=rock.

An input that starts with / works differently. It starts from the top of the site. So /search with the same base gives https://example.com/search.

1const url = new URL(input, base);2console.log(url.href);3console.log(url.protocol);4console.log(url.hostname);5console.log(url.searchParams.getAll("tag"));

Try the "Unicode domain" preset. The hostname row shows the punycode form. In href, the letters é and í in the path and hash turn into codes like %C3%A9. This is called percent-encoding; a later section explains it.

Then try the "Username + password" preset. A URL can hold a username and a password before the @. Real apps should not show them or write them to logs, because anyone who sees the URL would see the password.

The query string is the part after ?. It is a list of name=value pairs, joined by &. For example, ?q=boots&page=2 has two pairs: q is boots, and page is 2.

The same name can appear more than once. Shops often do this for filters: ?tag=js&tag=web.

Every URL object has a searchParams property. It is linked to the URL. When you change searchParams, url.search and url.href change right away. These are its main methods:

• set(name, value) puts in one value. It replaces any old values with that name.
• append(name, value) adds one more value. Old values with that name stay.
• delete(name) removes every pair with that name.
• has(name) returns true if a pair with that name is there.
• get(name) returns the first value for that name, or null if there is none.
• getAll(name) returns every value for that name, as an array.
• sort() puts the pairs in order by name.
• toString() writes the query string, without the ?.

You can also loop over it with for...of. Each step of the loop gives one [name, value] pair.

const params = new URLSearchParams("tag=js&tag=web&page=2");
params.set("page", "3");
params.append("tag", "url");
console.log(params.get("tag"));
console.log(params.getAll("tag"));
console.log(params.has("page"));
params.delete("page");
params.sort();
console.log(params.toString());

• Line 1 makes params from a query string. It has two tag values, js and web, and a page, 2.
• Line 2 uses set to replace page 2 with 3.
• Line 3 uses append to add a third tag, url. The two old tags stay.
• Line 4 uses get, so it prints only the first tag: js.
• Line 5 uses getAll, so it prints all three: [ 'js', 'web', 'url' ].
• Line 6 prints true, because page is still there.
• Line 7 removes page. Line 8 sorts the pairs by name. Only tag pairs are left, and sort keeps pairs with the same name in their old order.
• Line 9 prints tag=js&tag=web&tag=url.

1const url = new URL("https://example.com/search");2url.searchParams.set("q", query);3for (const tag of tags) url.searchParams.append("tag", tag);4url.searchParams.set("page", page);5url.searchParams.sort();6console.log(url.href);7console.log([...url.searchParams]);

Look at the spaces in the lab's URL. URLSearchParams writes each space as +. Web forms have always sent spaces this way, so query strings follow the same rule. The rule has a long name: application/x-www-form-urlencoded. When you read a value back through URLSearchParams, each + turns back into a space.

Some characters have a job in a URL:

• & separates one pair from the next.
• = separates a name from its value.
• ? starts the query string.
• # starts the hash.
• / separates the folders in the path.

Sometimes these characters are part of the data, like the & in rock & roll. Then they must be written in a safe form, so they are not read as URL punctuation.

That safe form is called percent-encoding. Each special character becomes % and a code. For example, & becomes %26, and a space becomes %20. Some characters, like emoji, need several codes. To encode text means to write it in this safe form. To decode it means to turn it back into normal text.

1encodeURIComponent(value);2encodeURI(value);3new URLSearchParams({ q: value }).toString();4decodeURIComponent("%E0%A4%A"); // throws URIError

The table lists the tools. Each row says what one tool is for and what it does.

Here is the difference on one folder name, reports/2026. The slash is part of the name, not a split between two folders.

new URL() throws an error for a bad address. Sometimes you just want a yes or no answer. For example, a form may want to check what a user typed. Two tools help. They are static methods: you call them on URL itself, not on a URL object.

• URL.canParse(input, base?) returns true or false. It never throws.
• URL.parse(input, base?) returns a URL object, or null if the input is not valid. It never throws either.

Both tools are new. URL.parse is the newest, so some older browsers don't have it yet. Check that it exists before you use it, for example with typeof URL.parse === "function". This check is called feature detection.

Next is the bug these tools help you avoid. An API here is an address your code calls to get data from a server. The code below builds an API address in two ways:

• Line 2 joins the search text onto the address with +.
• Lines 3 to 5 use URL and searchParams.

Joining works for a plain word. It breaks when the search text has an &.

1const base = "https://api.example.com/search";Run2const unsafe = base + "?q=" + "rock & roll";3const url = new URL(base);4url.searchParams.set("q", "rock & roll");5url.searchParams.append("tag", "music & culture");6console.log(unsafe);7console.log(url.href);

The safe version treats the search text as data. set and append encode each value. So the server gets exactly what the user typed, and exactly the tag you added.

Where you’ll use this

Your code will meet URLs in many places: menu links, share buttons, page numbers, sign-in pages that send you back where you were, and every lesson that fetches data from a server. The steps are almost always the same:

1. Start from a base address you trust.
2. Add path or query parts with the URL tools, not with +.
3. Read href at the end.

Some places you'll do this:

• Search pages: start from new URL(location.href). location.href is the address of the current page. Change searchParams, then show the new address in the address bar.
• API calls: start from the API's base address. Append filters and page numbers. Then pass url.href to fetch, the function that asks a server for data.
• Return addresses: a sign-in page often gets a "go back to" URL. Check it with URL.canParse. Then compare its origin with your own site before you send the user there.
• Links you build: encode each changing folder name with encodeURIComponent if it might contain /.

Marketing links often carry labels in the query string. utm_source says where the click came from. utm_campaign names the campaign.

const url = new URL("https://example.com/news?utm_source=email&utm_campaign=fall");
console.log(url.searchParams.get("utm_source"));
console.log(url.searchParams.get("utm_campaign"));

Line 1 parses the full link once. Line 2 reads utm_source and prints email. Line 3 reads utm_campaign and prints fall. If a name is missing, get returns null. That is easier than cutting the raw text at each &.

function safeLink(input, base) {
  if (!URL.canParse(input, base)) return null;
  const url = new URL(input, base);
  return url.protocol === "https:" ? url.href : null;
}
console.log(safeLink("https://example.com/help", "https://app.example.com/"));
console.log(safeLink("javascript:alert(1)", "https://app.example.com/"));

• Line 2 returns null if URL.canParse says the text is not a URL at all.
• Line 4 returns the link only if its protocol is https:. Otherwise it returns null.
• Line 6 passes an https link, so it prints https://example.com/help.
• Line 7 passes javascript:alert(1). That is a valid URL, but clicking it runs code. Its protocol is javascript:, so line 4 returns null.

For a real return address, also compare origin with a list of sites you allow. Checking only that the text starts with https:// doesn't tell you which site the user will land on.

Common misconceptions

• “A URL is just a string.” You can show a URL as a string. But it has parts and rules. new URL() knows these rules. String methods like split don't.
• “The hash goes to the server.” The browser keeps the hash. It uses it to jump to a spot in the page. Requests to the server don't include it.
• “encodeURI and encodeURIComponent do the same thing.” encodeURI is for a whole address, so it leaves punctuation like / and ? alone. encodeURIComponent is for one piece of data, so it encodes them.
• “A plus sign always means a space.” Only in query strings, which follow the web form rule. URLSearchParams uses that rule. decodeURIComponent("+") returns +, not a space.
• “Turning params into an object keeps repeated names.” Object.fromEntries(new URLSearchParams("tag=js&tag=web")) keeps only the last tag, web. An object can't have two properties with the same name. Use getAll to get every value.

Pick your answer before you check it. Then read every explanation.

Key takeaways

• new URL(input, base?) splits an address into parts. It works out a relative address from the base, tidies the parts, and throws a TypeError for an invalid URL.
• url.searchParams is linked to url.search. It is the safest way to build a query string.
• URLSearchParams writes a space as +. encodeURIComponent writes it as %20.
• encodeURI is for a whole URL. encodeURIComponent is for one piece of data.
• URL.canParse returns true or false. URL.parse returns a URL or null, in browsers that have it.

Up next: Streams & progress.