Node.js v24.7.0 documentation

new URL(input[, base])#

• input <string> The absolute or relative input URL to parse. If input is relative, then base is required. If input is absolute, the base is ignored. If input is not a string, it is converted to a string first.
• base <string> The base URL to resolve against if the input is not absolute. If base is not a string, it is converted to a string first.

Creates a new URL object by parsing the input relative to the base. If base is passed as a string, it will be parsed equivalent to new URL(base).

const myURL = new URL('/foo', 'https://example.org/');
// https://example.org/foo copy

The URL constructor is accessible as a property on the global object. It can also be imported from the built-in url module:

import { URL } from 'node:url';
console.log(URL === globalThis.URL); // Prints 'true'.console.log(URL === require('node:url').URL); // Prints 'true'.copy

A TypeError will be thrown if the input or base are not valid URLs. Note that an effort will be made to coerce the given values into strings. For instance:

const myURL = new URL({ toString: () => 'https://example.org/' });
// https://example.org/ copy

Unicode characters appearing within the host name of input will be automatically converted to ASCII using the Punycode algorithm.

const myURL = new URL('https://測試');
// https://xn--g6w251d/ copy

In cases where it is not known in advance if input is an absolute URL and a base is provided, it is advised to validate that the origin of the URL object is what is expected.

let myURL = new URL('http://Example.com/', 'https://example.org/');
// http://example.com/

myURL = new URL('https://Example.com/', 'https://example.org/');
// https://example.com/

myURL = new URL('foo://Example.com/', 'https://example.org/');
// foo://Example.com/

myURL = new URL('http:Example.com/', 'https://example.org/');
// http://example.com/

myURL = new URL('https:Example.com/', 'https://example.org/');
// https://example.org/Example.com/

myURL = new URL('foo:Example.com/', 'https://example.org/');
// foo:Example.com/ copy

url.hash#

• Type: <string>

Gets and sets the fragment portion of the URL.

const myURL = new URL('https://example.org/foo#bar');
console.log(myURL.hash);
// Prints #bar

myURL.hash = 'baz';
console.log(myURL.href);
// Prints https://example.org/foo#baz copy

Invalid URL characters included in the value assigned to the hash property are percent-encoded. The selection of which characters to percent-encode may vary somewhat from what the url.parse() and url.format() methods would produce.

url.host#

• Type: <string>

Gets and sets the host portion of the URL.

const myURL = new URL('https://example.org:81/foo');
console.log(myURL.host);
// Prints example.org:81

myURL.host = 'example.com:82';
console.log(myURL.href);
// Prints https://example.com:82/foo copy

Invalid host values assigned to the host property are ignored.

url.hostname#

• Type: <string>

Gets and sets the host name portion of the URL. The key difference between url.host and url.hostname is that url.hostname does not include the port.

const myURL = new URL('https://example.org:81/foo');
console.log(myURL.hostname);
// Prints example.org

// Setting the hostname does not change the port
myURL.hostname = 'example.com';
console.log(myURL.href);
// Prints https://example.com:81/foo

// Use myURL.host to change the hostname and port
myURL.host = 'example.org:82';
console.log(myURL.href);
// Prints https://example.org:82/foo copy

Invalid host name values assigned to the hostname property are ignored.

url.href#

• Type: <string>

Gets and sets the serialized URL.

const myURL = new URL('https://example.org/foo');
console.log(myURL.href);
// Prints https://example.org/foo

myURL.href = 'https://example.com/bar';
console.log(myURL.href);
// Prints https://example.com/bar copy

Getting the value of the href property is equivalent to calling url.toString().

Setting the value of this property to a new value is equivalent to creating a new URL object using new URL(value). Each of the URL object's properties will be modified.

If the value assigned to the href property is not a valid URL, a TypeError will be thrown.

url.origin#

• Type: <string>

Gets the read-only serialization of the URL's origin.

const myURL = new URL('https://example.org/foo/bar?baz');
console.log(myURL.origin);
// Prints https://example.org copy

const idnURL = new URL('https://測試');
console.log(idnURL.origin);
// Prints https://xn--g6w251d

console.log(idnURL.hostname);
// Prints xn--g6w251d copy

url.password#

• Type: <string>

Gets and sets the password portion of the URL.

const myURL = new URL('https://abc:xyz@example.com');
console.log(myURL.password);
// Prints xyz

myURL.password = '123';
console.log(myURL.href);
// Prints https://abc:123@example.com/ copy

Invalid URL characters included in the value assigned to the password property are percent-encoded. The selection of which characters to percent-encode may vary somewhat from what the url.parse() and url.format() methods would produce.

url.pathname#

• Type: <string>

Gets and sets the path portion of the URL.

const myURL = new URL('https://example.org/abc/xyz?123');
console.log(myURL.pathname);
// Prints /abc/xyz

myURL.pathname = '/abcdef';
console.log(myURL.href);
// Prints https://example.org/abcdef?123 copy

Invalid URL characters included in the value assigned to the pathname property are percent-encoded. The selection of which characters to percent-encode may vary somewhat from what the url.parse() and url.format() methods would produce.

url.port