Building and parsing URLs
This guide covers how to use URL to build and take apart URLs, URLSearchParams to change query parameters, and Headers to prepare request headers. None of these three classes touches the network; the URLs and headers you build are sent with fetch().
Recommended approach
- Define the server's base URL as a constant, and use it as the second argument for every relative URL. The app's JS is loaded locally, so there is no "current page URL", and both
new URL('/x')andfetch('/api')fail. Writenew URL('/x', api)andfetch(new URL('/api', api))instead. For the reason, see URLs must be complete. - Change query parameters with
url.searchParams, not by building strings yourself.searchParamshandles encoding, so spaces,&,=, and non-ASCII characters in values don't break the URL's structure. When you assign tourl.searchdirectly, the content is written as is, without encoding. - When a URL comes from user input or a server response and may not be valid, use
URL.canParse()orURL.parse(). They don't throw. - Request headers can be a
Headersor a plain object. UseHeaderswhen you need to read by name, check whether one exists, or append values with the same name; it is case-insensitive. When you only pass them tofetch()once, a plain object is shorter.
First example
The code below builds an API URL with query parameters, then prepares a set of request headers. It needs no interface and runs directly at the top level of main.js.
// 1. Parse a full URL
const url = new URL('https://api.example.com/v1/items?page=2');
// 2. Change one query parameter and add another
url.searchParams.set('page', '3');
url.searchParams.append('q', '中 文');
console.log(url.href);
// 3. Read individual parts
console.log(url.hostname, url.pathname);
// 4. Prepare request headers. Names are case-insensitive
const headers = new Headers({ 'Content-Type': 'application/json' });
headers.set('Authorization', 'Bearer abc');
console.log(headers.get('content-type'));Result: The console prints three lines.
https://api.example.com/v1/items?page=3&q=%E4%B8%AD+%E6%96%87api.example.com /v1/itemsapplication/json
This code hasn't been run as a whole in the simulator. Every API it uses has been run in the acceptance tests.
The code in each section below creates its own variables and doesn't reuse these.
Taking a URL apart
const parts = new URL('https://u:p@EXAMPLE.com:443/a/b/../c?x=1&y=2#f');
console.log(parts.protocol); // https:
console.log(parts.username); // u
console.log(parts.host); // example.com
console.log(parts.port); // Empty string
console.log(parts.pathname); // /a/c
console.log(parts.search); // ?x=1&y=2
console.log(parts.hash); // #f
console.log(parts.origin); // https://example.com
console.log(parts.href); // https://u:p@example.com/a/c?x=1&y=2#fResult: Each line prints what its comment shows. protocol includes the trailing colon, search the leading question mark, and hash the leading hash sign. The host is lowercased, the default port 443 is omitted, and .. in the path is resolved; see URLs are normalized.
Resolving a relative URL against a base
const api = 'https://api.example.com/v1/';
console.log(new URL('items', api).href);
console.log(new URL('/x', 'https://a.com').href);
console.log(new URL('../y', 'https://a.com/a/b/c').pathname);Result: It prints https://api.example.com/v1/items, https://a.com/x, and /a/y.
Checking whether text is a valid URL
console.log(URL.canParse('/x'));
console.log(URL.canParse('https://a.com/x'));
const parsed = URL.parse('https://a.com/x');
if (parsed) {
console.log(parsed.pathname);
}Result: It prints false, true, then /x. URL.parse() returns null when it can't parse, so check for null before using the result.
Changing one part of a URL
const page = new URL('https://a.com/p');
page.pathname = 'q';
page.hash = 'top';
console.log(page.href);Result: It prints https://a.com/q#top. The leading / can be omitted when assigning pathname, # when assigning hash, and ? when assigning search; they are added automatically.
After assigning protocol, username, password, host, hostname, port, or pathname, the whole URL is parsed again. When the new value would make the URL invalid, the assignment has no effect and the URL stays as it was, without throwing.
Encoding query parameter values
const search = new URL('https://api.example.com/search');
search.searchParams.set('q', '中 文');
console.log(search.href);Result: It prints https://api.example.com/search?q=%E4%B8%AD+%E6%96%87. The space is encoded as +, and the non-ASCII characters are encoded as UTF-8; see Encoding rules.
Reading multiple query parameters with the same name
const repeated = new URLSearchParams('a=1&b=2&a=3');
console.log(repeated.get('a'));
console.log(repeated.getAll('a'));
console.log(repeated.size);Result: It prints 1, ['1', '3'], then 3. get() returns only the first; use getAll() to get them all.
Replacing, appending, and deleting query parameters
const edits = new URLSearchParams('a=1&b=2&a=3');
edits.set('a', '9');
console.log(edits.toString());
edits.append('c', '中 文');
console.log(edits.toString());
edits.delete('a');
console.log(edits.toString());Result: It prints a=9&b=2, a=9&b=2&c=%E4%B8%AD+%E6%96%87, then b=2&c=%E4%B8%AD+%E6%96%87.
set() replaces the first parameter with that name with the new value and deletes the rest with the same name, keeping the position. When there is no parameter with that name, it is added at the end.
A URL and its query parameters stay in sync
const synced = new URL('https://a.com/?k=1');
synced.searchParams.append('k2', 'v2');
console.log(synced.search);
synced.search = '?z=9';
console.log(synced.searchParams.get('z'));Result: It prints ?k=1&k2=v2 and 9. Changing searchParams updates search and href; changing search or href updates searchParams.
Appending headers with the same name
const accept = new Headers();
accept.append('Accept', 'a');
accept.append('accept', 'b');
console.log(accept.get('ACCEPT'));Result: It prints a, b. Multiple values with the same name are read as one string joined with , . To overwrite instead of append, use set().
Reading multiple Set-Cookie headers
const cookies = new Headers();
cookies.append('Set-Cookie', 'x=1');
cookies.append('Set-Cookie', 'y=2');
console.log(cookies.getSetCookie());Result: It prints ['x=1', 'y=2']. Set-Cookie values may themselves contain commas and can't be joined into one string, so use getSetCookie() to get an array.
Iterating over all headers
const all = new Headers({ 'Content-Type': 'application/json', Accept: 'a' });
for (const [name, value] of all) {
console.log(name, value);
}Result: It prints accept a and content-type application/json. Names are all lowercase and sorted alphabetically by name, regardless of the order they were added. Set-Cookie appears as many times as there are entries.
See also
URL: the parts of a URLURLSearchParams: reading and writing query parametersHeaders: request and response headersfetch(): sending the URLs and headers you build