URL API — Glossary

URL API is the standard interface, available as the URL class in browsers and Node.js, that parses a web address into named parts and can rebuild it safely. It is defined by the WHATWG URL Standard, and the same parsing rules apply in every conforming runtime. The constructor throws a TypeError when the string is not a valid absolute URL.

How it works

Calling new URL(input, base) runs the standard's parsing algorithm. The result is an object with writable properties: protocol, username, password, host, hostname, port, pathname, search, hash and href, plus the read-only origin and searchParams. Setting any property re-serializes the whole address, so href always stays consistent.

The parser normalizes as it goes:

The scheme and host are lowercased, and an internationalized host such as münchen.de becomes its punycode form.
Dot segments in the path are resolved, so /a/./b/../c becomes /a/c.
Spaces and other unsafe characters in the path, query and fragment are percent-encoded.
A port equal to the scheme's default is dropped. The defaults are 21 for ftp, 80 for http and ws, and 443 for https and wss.
If a second argument is given, a relative input is resolved against that base, the way a browser resolves an href on a page.

const u = new URL('https://user:pw@Example.COM:443/a/./b/../c d?q=1&q=2#frag');
console.log(u.href);
console.log(u.origin, '|', u.host, '|', u.pathname, '|', u.search, '|', u.hash);
console.log(new URL('../x?y=1', 'https://example.com/a/b/c').href);
console.log(URL.canParse('/path'), URL.canParse('/path', 'https://a.com'));
try { new URL('/path'); } catch (e) { console.log(e.name, '|', e.message); }

Output from Node.js 22.22.0:

https://user:pw@example.com/a/c%20d?q=1&q=2#frag
https://example.com | example.com | /a/c%20d | ?q=1&q=2 | #frag
https://example.com/a/x?y=1
false true
TypeError | Invalid URL

How do you check if a string is a valid URL in JavaScript?

Call URL.canParse(string), which returns true when the constructor would succeed and false when it would throw. It replaces the older try and catch around new URL. For a relative string, pass a base as the second argument, with the base as a second string. URL.parse(string) is a related static method that returns null instead of throwing. Both are newer than the constructor, so check your minimum browser and Node.js versions before relying on them.

Why does new URL throw "Invalid URL"?

It throws because the input is relative and no base was supplied, or because the host or scheme is malformed. The string /path fails on its own and works with a base. A bare host like example.com also fails, because without a scheme it is read as a relative path. Add the scheme and two slashes in front.

Common pitfalls

Treating validity as safety: a successfully parsed URL can still point at javascript: or an internal address. Check protocol and hostname against an allowlist before you fetch or redirect.
Expecting an origin from every scheme: data: and many file: URLs report the string "null" as origin because they have an opaque origin. Do not compare it for equality across documents.
Building a query by string concatenation: a value containing & or # corrupts the address. Set values through searchParams so encoding is automatic.
Forgetting the leading characters: search includes the ? and hash includes the #, but both are empty strings when absent, not null.
Reading port for defaults: port is the empty string for the default port, so a URL that ends in :443 on an https address reports port as an empty string.
Assuming href is the input: href is the normalized form. Compare normalized values, not raw strings, when deduplicating links.

Related terms

URLSearchParams — the query-string helper exposed as url.searchParams
Query string — the part after the question mark that search holds
URL encoding — the percent-encoding the parser applies to unsafe characters
Fetch API — accepts a URL object directly as its first argument
HTTPS — the scheme whose default port 443 the parser drops