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.