JavaScript Reference ยท Browser and Web APIs
The URL class
Reference for the URL class: parse addresses into parts, resolve relative links, edit pathname and search, validate input with URL.canParse(), and avoid pitfalls.
The URL class parses an address into named parts (protocol, host, path, query, fragment) and lets you read or change each one safely. The browser applies the same parsing rules it uses for links, so new URL() is much more reliable than splitting strings or using regular expressions.
Setting a property updates the whole address and re-encodes characters as needed. The searchParams property gives you a live URLSearchParams for the query string.
const url = new URL("https://example.com:8080/a/b?x=1#top"); console.log(url.hostname, url.pathname);
Try it
Press Run (or Ctrl + Enter) to see the console output here.
No output.
Press Run (or Ctrl + Enter) to see the console output here.
No output.
Syntax
new URL(url) new URL(url, base) URL.canParse(url, base) // boolean URL.parse(url, base) // URL or null
| Name | Description |
|---|---|
url |
An absolute URL, or a relative one when base is given. |
base |
Optional string or URL that a relative url is resolved against. |
Properties (all readable, and writable except origin and searchParams):
| Property | Example value |
|---|---|
href |
the whole URL as a string |
origin |
https://example.com:8443 (read-only) |
protocol |
https: (includes the colon) |
username, password |
credentials in the address |
host |
example.com:8443 (hostname plus non-default port) |
hostname |
example.com |
port |
"8443", or "" for the default port |
pathname |
/items/42 |
search |
?color=red (empty string if none) |
searchParams |
live URLSearchParams |
hash |
#reviews (empty string if none) |
Methods: toString() and toJSON() both return href. Static URL.createObjectURL(blob) and URL.revokeObjectURL(url) create and free temporary blob: addresses.
Exceptions: new URL() throws a TypeError if the string cannot be parsed.
Usage notes
- Relative URLs need a base.
new URL("/path")throws; passlocation.hrefor an origin as the second argument. - Validate with
URL.canParse()instead of try/catch when you only need a yes or no.URL.parse()returnsnullfor bad input, but it is newer, so check a compatibility table. - Check the protocol before trusting a user-supplied link:
javascript:anddata:URLs parse fine. Allow onlyhttp:andhttps:when you render links. - Compare origins, not strings.
a.origin === b.originis the right same-origin test. - Do not build URLs by concatenation. Use
searchParams.set()so values are encoded correctly. - Credentials in the URL (
user:pw@) are discouraged and not accepted by some APIs; send them in headers instead. - Blob URLs leak memory until you call
URL.revokeObjectURL(). - Setting
hostorhostnameto invalid text is silently ignored; checkhrefafterwards if input is untrusted.
Browser support
URL is supported in every current browser and in Node.js. URL.canParse() and URL.parse() are more recent, so check a compatibility table.