How to Parse URLs in JavaScript: The URL API vs Manual Parsing

Parsing URLs sounds simple until you actually try it. There are dozens of edge cases: URLs with no path, query parameters containing = in values, fragments that include ?, internationalized domain names. The URL API handles all of this correctly. Here's how to use it.

The URL API

URL is a browser-native class (also available in Node.js since v10) that parses a URL string into its component parts:

const url = new URL('https://example.com:8080/path/page?q=hello+world&lang=en#section');

url.protocol  // "https:"
url.hostname  // "example.com"
url.port      // "8080"
url.host      // "example.com:8080"
url.pathname  // "/path/page"
url.search    // "?q=hello+world&lang=en"
url.hash      // "#section"
url.origin    // "https://example.com:8080"
url.href      // full URL string

The parser handles edge cases automatically. Standard ports are omitted from host: http://example.com:80/ gives host === "example.com".

URLSearchParams: the right way to handle query strings

Don't split on & and = to parse query parameters — values can contain encoded & and = characters. Use URLSearchParams:

const url = new URL('https://example.com?q=hello+world&tags=js&tags=css');
const params = url.searchParams;

params.get('q')      // "hello world" — decodes + as space
params.getAll('tags') // ["js", "css"] — handles repeated params
params.has('tags')   // true

// Iterate all params
for (const [key, value] of params) {
  console.log(key, value);
}
// q hello world
// tags js
// tags css

Building query strings

const params = new URLSearchParams({
  q: 'hello world',
  sort: 'date',
  page: '1'
});
params.toString()  // "q=hello+world&sort=date&page=1"

// Append without replacing
params.append('tags', 'javascript');
params.append('tags', 'css');
params.toString()  // "q=hello+world&sort=date&page=1&tags=javascript&tags=css"

Modifying URL parameters

const url = new URL('https://example.com?page=1&sort=date');

url.searchParams.set('page', '2');  // update
url.searchParams.delete('sort');    // remove
url.searchParams.append('filter', 'active');  // add

url.href  // "https://example.com/?page=2&filter=active"

Relative URL resolution

URL handles relative URLs when given a base:

new URL('/about', 'https://example.com')
  .href  // "https://example.com/about"

new URL('../images/photo.jpg', 'https://example.com/blog/post/')
  .href  // "https://example.com/blog/images/photo.jpg"

new URL('?page=2', 'https://example.com/articles')
  .href  // "https://example.com/articles?page=2"

This is the correct way to resolve relative links when scraping or building link crawlers.

URL encoding and decoding

URL handles percent-encoding automatically:

const url = new URL('https://example.com/search');
url.searchParams.set('q', 'café & creme brûlée');
url.href  // "https://example.com/search?q=caf%C3%A9+%26+creme+br%C3%BBl%C3%A9e"

For manual encoding/decoding:

// Encode a component value (e.g., query parameter value)
encodeURIComponent('hello world & more')  // "hello%20world%20%26%20more"

// Encode a full URL (preserves :, /, ?, =, &, #, @)
encodeURI('https://example.com/path?q=hello world')
// "https://example.com/path?q=hello%20world"

// Decode
decodeURIComponent('hello%20world')  // "hello world"

Use the URL Encoder/Decoder to manually encode/decode URL components in the browser without writing code.

Validating URLs

function isValidUrl(string) {
  try {
    new URL(string);
    return true;
  } catch {
    return false;
  }
}

isValidUrl('https://example.com')  // true
isValidUrl('not a url')            // false
isValidUrl('//example.com')        // true — protocol-relative URL

Note: //example.com is a valid protocol-relative URL. If you want to require a specific protocol:

function isHttpUrl(string) {
  try {
    const url = new URL(string);
    return url.protocol === 'http:' || url.protocol === 'https:';
  } catch {
    return false;
  }
}

Extracting the domain from a URL

new URL('https://sub.example.co.uk/path').hostname
// "sub.example.co.uk"

// hostname vs host:
new URL('https://example.com:443/path').host      // "example.com:443"
new URL('https://example.com:443/path').hostname  // "example.com"

hostname strips the port. host includes it.

URL in Node.js

URL is globally available in Node.js since v10. For older compatibility, import it:

const { URL, URLSearchParams } = require('url');

It's also available in Web Workers and Service Workers in the browser.

What about the legacy document.createElement('a') trick?

Before the URL API, developers used a DOM <a> element to parse URLs:

const a = document.createElement('a');
a.href = 'https://example.com/path';
a.hostname  // "example.com"

This only works in the browser (not Node.js), can behave differently across browsers for edge cases, and doesn't support URLSearchParams. Use the URL API instead — it's available everywhere that matters and handles edge cases correctly.

---

The URL API is one of those Web APIs that, once you start using it, you wonder how you ever parsed URLs without it. URLSearchParams in particular eliminates an entire category of bugs from query string handling. If you're still splitting on ? and &, there's a better way.