url API properties

All property specifications use the url object, where not specified, the url object is assumed to be initialized, such as with the const url = new URL() constructor statement.

The following properties are available.

url.hash

Gets and sets the fragment portion of the URL.

Syntax
url.hash
Example
const { URL } = require('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

url.host

Gets and sets the host portion of the URL.

Syntax
url.host
Guidelines
The key difference between the url.host and url.hostname property is that the url.hostname property does not include the port.
Example
const { URL } = require('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

url.hostname

Gets and sets the hostname portion of the URL.

Syntax
url.hostname
Guidelines
The key difference between the url.hostname and url.host property is that the url.hostname property does not include the port.
Example
const { URL } = require('url');
const myURL = new URL('https://example.org:81/foo');
console.log(myURL.hostname);  // Prints example.org

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

url.href

Gets and sets the serialized URL.

Syntax
url.href
Guidelines
The url.href property is equivalent to the calling of the url.toString() API. Setting the value of this property to a new value is equivalent to creating a new URL object with the new URL(value) constructor.
Example
const { URL } = require('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

url.origin

Gets the read-only serialization of the URL origin.

Syntax
url.origin
Example
const { URL } = require('url');
const myURL = new URL('https://example.org/foo/bar?baz');
console.log(myURL.origin);  // Prints https://example.org

url.password

Gets and sets the password portion of the URL.

Syntax
url.password
Example
const { URL } = require('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

url.pathname

Gets and sets the path portion of the URL.

Syntax
url.pathname
Example
const { URL } = require('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

url.port

Gets and sets the port portion of the URL.

Syntax
url.port
Guidelines
The port value is an integer or a string that contains a number in the range 0 - 65535. The following rules apply to the url.port property.
  • When a value is set to the default port of the URL objects for a protocol, the port value becomes the empty string ('').
  • When an invalid string is assigned to the port property, but it begins with a number, the leading number is assigned to the port.
  • When the number is beyond the valid range, the out-of-range numbers are ignored.
  • Nonintegers are truncated and then are assigned to the port.
Example
const { URL } = require('url');
const myURL = new URL('https://example.org:8888');
console.log(myURL.port);  // Prints 8888

// Default ports are automatically transformed to the empty string
// (HTTPS protocol's default port is 443)
myURL.port = '443';
console.log(myURL.port);  // Prints the empty string
console.log(myURL.href);  // Prints https://example.org/

myURL.port = 1234;
console.log(myURL.port);  // Prints 1234
console.log(myURL.href);  // Prints https://example.org:1234/

// Completely invalid port strings are ignored
myURL.port = 'abcd';
console.log(myURL.port);  // Prints 1234

// Leading numbers are treated as a port number
myURL.port = '5678abcd';
console.log(myURL.port);  // Prints 5678

// Non-integers are truncated
myURL.port = 1234.5678;
console.log(myURL.port);  // Prints 1234

// Out-of-range numbers are ignored
myURL.port = 1e10;
console.log(myURL.port);  // Prints 1234

url.protocol

Gets and sets the protocol portion of the URL.

Syntax
url.protocol
Example
const { URL } = require('url');
const myURL = new URL('https://example.org');
console.log(myURL.protocol);  // Prints https:

myURL.protocol = 'ftp';
console.log(myURL.href);  // Prints ftp://example.org/

url.search

Gets and sets the serialized query portion of the URL.

Syntax
url.search
Example
const { URL } = require('url');
const myURL = new URL('https://example.org/abc?123');
console.log(myURL.search);  // Prints ?123

myURL.search = 'abc=xyz';
console.log(myURL.href);  // Prints https://example.org/abc?abc=xyz

url.searchParams

Gets the searchparams object that represents the query parameters of the URL.

Syntax
url.searchParams
Guidelines
The url.searchParams property gets the searchparams object that is created by #URLSearchParamsClassConstructors.

The url.searchParams property is read-only. To replace the entire query parameters of the URL, use the url.search property to set.

url.username

Gets and sets the username portion of the URL.

Syntax
url.username
Example
const { URL } = require('url');
const myURL = new URL('https://abc:xyz@example.com');
console.log(myURL.username); // Prints abc

myURL.username = '123';
console.log(myURL.href);  // Prints https://123:xyz@example.com/