URLs

The URL class parses URLs and allows modification of existing URLs. URL objects are created with URL() constructor, passing an absolute URL string as the argument, or, alternatively, a relative URL as the first argument and absolute URL that is relative to the first one as the second argument.

let url = new URL("http://localhost:8080/path?q=term#urls");
url.href; // => 'http://localhost:8080/path?q=term#urls'
url.origin; // => 'http://localhost:8080'
url.protocol; // => 'http:'
url.host; // => 'localhost:8080'
url.hostname; // => 'localhost'
url.port; // => '8080'
url.pathname; // => '/path'
url.search; // => ?q=term'
url.hash; // => '#urls'

URLs can include a username and password, which URL class can parse as URL components.

let login = new URL("ftp://admin:[email protected]/");
login.href; // => 'ftp://admin:[email protected]/'
login.origin; // => 'ftp://ftp.example.com'
login.username; // => 'admin'
login.password; // => 'pass'

The origin property is read-only property, however other properties can be set to other values to manipulate the URL object.

let website = new URL("https://romanakchurin.com");
website.pathname = "api/search";
website.search = "q=js";
website.toString(); // => 'https://romanakchurin.com/api/search?q=js'

URL class correctly adds punctuation and escapes special characters in URLs when required. When you read href property of the URL object, it reassembles all parts of the URL into the canonical form of the URL. Setting the href property to a new value is equivalent to calling URL() constructor again.

let example = new URL("https://example.com");
example.pathname = "path with spaces";
example.search = "q=id#num";
example.pathname; // => '/path%20with%20spaces'
example.search; // => '?q=id%23num'
example.href; // => 'https://example.com/path%20with%20spaces?q=id%23num'

It is possible for a URL to have multiple search parameters of the same name, such as ?opts=1&opts=2. This is commonly used in web applications to pass multiple values for the same parameter name. Node.js, for example, will store such values in an array. To encode such parameter names into a query string, use the class URLSearchParams().

let x = new URL("https://x.com");
let params = new URLSearchParams();
params.append("q", "term");
params.append("opts", "1");
params.append("opts", "2");
params.toString(); // => 'q=term&opts=1&opts=2'
x.search = params;
x.href; // => 'https://x.com/?q=term&opts=1&opts=2'

The searchParams property of the URL class is a read-only reference to a URLSearchParams() object within the URL object. You can get, set, add, delete, and sort the parameters encoded into the query portion of the URL with URLSearchParams() API.

let rt = new URL("https://rt.com/search");
rt.search; // => ''
rt.searchParams.append("q", "russia");
rt.search; // => '?q=russia'
rt.searchParams.set("q", "europe");
rt.search; // => '?q=europe'
rt.searchParams.get("q"); // => 'europe'
rt.searchParams.has("q"); // => true
rt.searchParams.has("opts"); // => false
rt.searchParams.append("opts", "1");
rt.searchParams.append("opts", "2");
rt.search; // => '?q=europe&opts=1&opts=2'
rt.searchParams.get("opts"); // => '1'
rt.searchParams.getAll("opts"); // => ['1', '2']
rt.searchParams.sort();
rt.search; // => '?opts=1&opts=2&q=europe'
rt.searchParams.set("opts", "r");
rt.search; // => '?opts=r&q=europe'
[...rt.searchParams]; // => [['opts', 'r'], ['q', 'europe']]
rt.searchParams.delete("opts");
rt.search; // => '?q=europe'
rt.href; // => 'https://rt.com/search?q=europe'