Skip to content
Tutorials Center
My learning

Topics

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.

JavaScript
const url = new URL("https://example.com:8080/a/b?x=1#top");
console.log(url.hostname, url.pathname);

Try it

JS Take a URL apart

Press Run (or Ctrl + Enter) to see the console output here.

No output.

JS Resolve, edit and validate

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Syntax

JavaScript
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; pass location.href or an origin as the second argument.
  • Validate with URL.canParse() instead of try/catch when you only need a yes or no. URL.parse() returns null for bad input, but it is newer, so check a compatibility table.
  • Check the protocol before trusting a user-supplied link: javascript: and data: URLs parse fine. Allow only http: and https: when you render links.
  • Compare origins, not strings. a.origin === b.origin is 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 host or hostname to invalid text is silently ignored; check href afterwards 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.