new URL(input[, base])#

• input<string> The absolute or relative input URL to parse. Ifinputis relative, thenbase is required. Ifinput is absolute, thebaseis ignored. Ifinput is not a string, it isconverted to a string first.
• base<string> The base URL to resolve against if theinput is notabsolute. Ifbase is not a string, it isconverted to a string first.

Creates a newURL object by parsing theinput relative to thebase. Ifbase is passed as a string, it will be parsed equivalent tonew URL(base).

const myURL =newURL('/foo','https://example.org/');// https://example.org/foocopy

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

ATypeError will be thrown if theinput orbase are not valid URLs. Notethat an effort will be made to coerce the given values into strings. Forinstance:

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

Unicode characters appearing within the host name ofinput will beautomatically converted to ASCII using thePunycode algorithm.

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

In cases where it is not known in advance ifinput is an absolute URLand abase is provided, it is advised to validate that theorigin oftheURL object is what is expected.

let myURL =newURL('http://Example.com/','https://example.org/');// http://example.com/myURL =newURL('https://Example.com/','https://example.org/');// https://example.com/myURL =newURL('foo://Example.com/','https://example.org/');// foo://Example.com/myURL =newURL('http:Example.com/','https://example.org/');// http://example.com/myURL =newURL('https:Example.com/','https://example.org/');// https://example.org/Example.com/myURL =newURL('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 =newURL('https://example.org/foo#bar');console.log(myURL.hash);// Prints #barmyURL.hash ='baz';console.log(myURL.href);// Prints https://example.org/foo#bazcopy

Invalid URL characters included in the value assigned to thehash propertyarepercent-encoded. The selection of which characters topercent-encode may vary somewhat from what theurl.parse() andurl.format() methods would produce.

url.host#

• Type:<string>

Gets and sets the host portion of the URL.

const myURL =newURL('https://example.org:81/foo');console.log(myURL.host);// Prints example.org:81myURL.host ='example.com:82';console.log(myURL.href);// Prints https://example.com:82/foocopy

Invalid host values assigned to thehost property are ignored.

url.hostname#

• Type:<string>

Gets and sets the host name portion of the URL. The key difference betweenurl.host andurl.hostname is thaturl.hostname doesnot include theport.

const myURL =newURL('https://example.org:81/foo');console.log(myURL.hostname);// Prints example.org// Setting the hostname does not change the portmyURL.hostname ='example.com';console.log(myURL.href);// Prints https://example.com:81/foo// Use myURL.host to change the hostname and portmyURL.host ='example.org:82';console.log(myURL.href);// Prints https://example.org:82/foocopy

Invalid host name values assigned to thehostname property are ignored.

url.href#

• Type:<string>

Gets and sets the serialized URL.

const myURL =newURL('https://example.org/foo');console.log(myURL.href);// Prints https://example.org/foomyURL.href ='https://example.com/bar';console.log(myURL.href);// Prints https://example.com/barcopy

Getting the value of thehref property is equivalent to callingurl.toString().

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

If the value assigned to thehref property is not a valid URL, aTypeErrorwill be thrown.

url.origin#

• Type:<string>

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

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

const idnURL =newURL('https://測試');console.log(idnURL.origin);// Prints https://xn--g6w251dconsole.log(idnURL.hostname);// Prints xn--g6w251dcopy

url.password#

• Type:<string>

Gets and sets the password portion of the URL.

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

Invalid URL characters included in the value assigned to thepassword propertyarepercent-encoded. The selection of which characters topercent-encode may vary somewhat from what theurl.parse() andurl.format() methods would produce.

url.pathname#

• Type:<string>

Gets and sets the path portion of the URL.

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

Invalid URL characters included in the value assigned to thepathnameproperty arepercent-encoded. The selection of which charactersto percent-encode may vary somewhat from what theurl.parse() andurl.format() methods would produce.

url.port#

• Type:<string>

Gets and sets the port portion of the URL.

The port value may be a number or a string containing a number in the range0 to65535 (inclusive). Setting the value to the default port of theURL objects givenprotocol will result in theport value becomingthe empty string ('').

The port value can be an empty string in which case the port depends onthe protocol/scheme:

Upon assigning a value to the port, the value will first be converted to astring using.toString().

If that string is invalid but it begins with a number, the leading number isassigned toport.If the number lies outside the range denoted above, it is ignored.

const myURL =newURL('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 stringconsole.log(myURL.href);// Prints https://example.org/myURL.port =1234;console.log(myURL.port);// Prints 1234console.log(myURL.href);// Prints https://example.org:1234/// Completely invalid port strings are ignoredmyURL.port ='abcd';console.log(myURL.port);// Prints 1234// Leading numbers are treated as a port numbermyURL.port ='5678abcd';console.log(myURL.port);// Prints 5678// Non-integers are truncatedmyURL.port =1234.5678;console.log(myURL.port);// Prints 1234// Out-of-range numbers which are not represented in scientific notation// will be ignored.myURL.port =1e10;// 10000000000, will be range-checked as described belowconsole.log(myURL.port);// Prints 1234copy

Numbers which contain a decimal point,such as floating-point numbers or numbers in scientific notation,are not an exception to this rule.Leading numbers up to the decimal point will be set as the URL's port,assuming they are valid:

myURL.port =4.567e21;console.log(myURL.port);// Prints 4 (because it is the leading number in the string '4.567e21')copy

url.protocol#

• Type:<string>

Gets and sets the protocol portion of the URL.

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

Invalid URL protocol values assigned to theprotocol property are ignored.

const u =newURL('http://example.org');u.protocol ='https';console.log(u.href);// https://example.org/copy

const u =newURL('http://example.org');u.protocol ='fish';console.log(u.href);// http://example.org/copy

const u =newURL('fish://example.org');u.protocol ='http';console.log(u.href);// fish://example.orgcopy

url.search#

• Type:<string>

Gets and sets the serialized query portion of the URL.

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

Any invalid URL characters appearing in the value assigned thesearchproperty will bepercent-encoded. The selection of whichcharacters to percent-encode may vary somewhat from what theurl.parse()andurl.format() methods would produce.

url.searchParams#

• Type:<URLSearchParams>

Gets theURLSearchParams object representing the query parameters of theURL. This property is read-only but theURLSearchParams object it providescan be used to mutate the URL instance; to replace the entirety of queryparameters of the URL, use theurl.search setter. SeeURLSearchParams documentation for details.

Use care when using.searchParams to modify theURL because,per the WHATWG specification, theURLSearchParams object usesdifferent rules to determine which characters to percent-encode. Forinstance, theURL object will not percent encode the ASCII tilde (~)character, whileURLSearchParams will always encode it:

const myURL =newURL('https://example.org/abc?foo=~bar');console.log(myURL.search);// prints ?foo=~bar// Modify the URL via searchParams...myURL.searchParams.sort();console.log(myURL.search);// prints ?foo=%7Ebarcopy

url.username#

• Type:<string>

Gets and sets the username portion of the URL.

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

Any invalid URL characters appearing in the value assigned theusernameproperty will bepercent-encoded. The selection of whichcharacters to percent-encode may vary somewhat from what theurl.parse()andurl.format() methods would produce.

url.toString()#

• Returns:<string>

ThetoString() method on theURL object returns the serialized URL. Thevalue returned is equivalent to that ofurl.href andurl.toJSON().

url.toJSON()#

• Returns:<string>

ThetoJSON() method on theURL object returns the serialized URL. Thevalue returned is equivalent to that ofurl.href andurl.toString().

This method is automatically called when anURL object is serializedwithJSON.stringify().

const myURLs = [newURL('https://www.example.com'),newURL('https://test.example.org'),];console.log(JSON.stringify(myURLs));// Prints ["https://www.example.com/","https://test.example.org/"]copy

URL.createObjectURL(blob)#

• blob<Blob>
• Returns:<string>

Creates a'blob:nodedata:...' URL string that represents the given<Blob>object and can be used to retrieve theBlob later.

const {Blob,  resolveObjectURL,} =require('node:buffer');const blob =newBlob(['hello']);const id =URL.createObjectURL(blob);// later...const otherBlob =resolveObjectURL(id);console.log(otherBlob.size);copy

The data stored by the registered<Blob> will be retained in memory untilURL.revokeObjectURL() is called to remove it.

Blob objects are registered within the current thread. If using WorkerThreads,Blob objects registered within one Worker will not be availableto other workers or the main thread.

URL.revokeObjectURL(id)#

• id<string> A'blob:nodedata:... URL string returned by a prior call toURL.createObjectURL().

Removes the stored<Blob> identified by the given ID. Attempting to revoke aID that isn't registered will silently fail.

URL.canParse(input[, base])#

• input<string> The absolute or relative input URL to parse. Ifinputis relative, thenbase is required. Ifinput is absolute, thebaseis ignored. Ifinput is not a string, it isconverted to a string first.
• base<string> The base URL to resolve against if theinput is notabsolute. Ifbase is not a string, it isconverted to a string first.
• Returns:<boolean>

Checks if aninput relative to thebase can be parsed to aURL.

const isValid =URL.canParse('/foo','https://example.org/');// trueconst isNotValid =URL.canParse('/foo');// falsecopy

URL.parse(input[, base])#

• input<string> The absolute or relative input URL to parse. Ifinputis relative, thenbase is required. Ifinput is absolute, thebaseis ignored. Ifinput is not a string, it isconverted to a string first.
• base<string> The base URL to resolve against if theinput is notabsolute. Ifbase is not a string, it isconverted to a string first.
• Returns:<URL> |<null>

Parses a string as a URL. Ifbase is provided, it will be used as the baseURL for the purpose of resolving non-absoluteinput URLs. Returnsnullif the parameters can't be resolved to a valid URL.

new URLPattern()#

Instantiate a new emptyURLPattern object.

new URLPattern(string[, baseURL][, options])#

• string<string> A URL string
• baseURL<string> |<undefined> A base URL string
• options<Object> Options

Parse thestring as a URL, and use it to instantiate a newURLPattern object.

IfbaseURL is not specified, it defaults toundefined.

An option can haveignoreCase boolean attribute which enablescase-insensitive matching if set to true.

The constructor can throw aTypeError to indicate parsing failure.

new URLPattern(obj[, baseURL][, options])#

• obj<Object> An input pattern
• baseURL<string> |<undefined> A base URL string
• options<Object> Options

Parse theObject as an input pattern, and use it to instantiate a newURLPattern object. The object members can be any ofprotocol,username,password,hostname,port,pathname,search,hash orbaseURL.

IfbaseURL is not specified, it defaults toundefined.

An option can haveignoreCase boolean attribute which enablescase-insensitive matching if set to true.

The constructor can throw aTypeError to indicate parsing failure.

urlPattern.exec(input[, baseURL])#

• input<string> |<Object> A URL or URL parts
• baseURL<string> |<undefined> A base URL string

Input can be a string or an object providing the individual URL parts. Theobject members can be any ofprotocol,username,password,hostname,port,pathname,search,hash orbaseURL.

IfbaseURL is not specified, it will default toundefined.

Returns an object with aninputs key containing the array of argumentspassed into the function and keys of the URL components which contains thematched input and matched groups.

const myPattern =newURLPattern('https://nodejs.org/docs/latest/api/*.html');console.log(myPattern.exec('https://nodejs.org/docs/latest/api/dns.html'));// Prints:// {//  "hash": { "groups": {  "0": "" },  "input": "" },//  "hostname": { "groups": {}, "input": "nodejs.org" },//  "inputs": [//    "https://nodejs.org/docs/latest/api/dns.html"//  ],//  "password": { "groups": { "0": "" }, "input": "" },//  "pathname": { "groups": { "0": "dns" }, "input": "/docs/latest/api/dns.html" },//  "port": { "groups": {}, "input": "" },//  "protocol": { "groups": {}, "input": "https" },//  "search": { "groups": { "0": "" }, "input": "" },//  "username": { "groups": { "0": "" }, "input": "" }// }copy

urlPattern.test(input[, baseURL])#

• input<string> |<Object> A URL or URL parts
• baseURL<string> |<undefined> A base URL string

Input can be a string or an object providing the individual URL parts. Theobject members can be any ofprotocol,username,password,hostname,port,pathname,search,hash orbaseURL.

IfbaseURL is not specified, it will default toundefined.

Returns a boolean indicating if the input matches the current pattern.

const myPattern =newURLPattern('https://nodejs.org/docs/latest/api/*.html');console.log(myPattern.test('https://nodejs.org/docs/latest/api/dns.html'));// Prints: truecopy

new URLSearchParams()#

Instantiate a new emptyURLSearchParams object.

new URLSearchParams(string)#

• string<string> A query string

Parse thestring as a query string, and use it to instantiate a newURLSearchParams object. A leading'?', if present, is ignored.

let params;params =newURLSearchParams('user=abc&query=xyz');console.log(params.get('user'));// Prints 'abc'console.log(params.toString());// Prints 'user=abc&query=xyz'params =newURLSearchParams('?user=abc&query=xyz');console.log(params.toString());// Prints 'user=abc&query=xyz'copy

new URLSearchParams(obj)#

• obj<Object> An object representing a collection of key-value pairs

Instantiate a newURLSearchParams object with a query hash map. The key andvalue of each property ofobj are always coerced to strings.

Unlikequerystring module, duplicate keys in the form of array values arenot allowed. Arrays are stringified usingarray.toString(), which simplyjoins all array elements with commas.

const params =newURLSearchParams({user:'abc',query: ['first','second'],});console.log(params.getAll('query'));// Prints [ 'first,second' ]console.log(params.toString());// Prints 'user=abc&query=first%2Csecond'copy

new URLSearchParams(iterable)#

• iterable<Iterable> An iterable object whose elements are key-value pairs

Instantiate a newURLSearchParams object with an iterable map in a way thatis similar to<Map>'s constructor.iterable can be anArray or anyiterable object. That meansiterable can be anotherURLSearchParams, inwhich case the constructor will simply create a clone of the providedURLSearchParams. Elements ofiterable are key-value pairs, and canthemselves be any iterable object.

Duplicate keys are allowed.

let params;// Using an arrayparams =newURLSearchParams([  ['user','abc'],  ['query','first'],  ['query','second'],]);console.log(params.toString());// Prints 'user=abc&query=first&query=second'// Using a Map objectconst map =newMap();map.set('user','abc');map.set('query','xyz');params =newURLSearchParams(map);console.log(params.toString());// Prints 'user=abc&query=xyz'// Using a generator functionfunction*getQueryPairs() {yield ['user','abc'];yield ['query','first'];yield ['query','second'];}params =newURLSearchParams(getQueryPairs());console.log(params.toString());// Prints 'user=abc&query=first&query=second'// Each key-value pair must have exactly two elementsnewURLSearchParams([  ['user','abc','error'],]);// Throws TypeError [ERR_INVALID_TUPLE]://        Each query pair must be an iterable [name, value] tuplecopy

urlSearchParams.append(name, value)#

• name<string>
• value<string>

Append a new name-value pair to the query string.

urlSearchParams.delete(name[, value])#

• name<string>
• value<string>

Ifvalue is provided, removes all name-value pairswhere name isname and value isvalue..

Ifvalue is not provided, removes all name-value pairs whose name isname.

urlSearchParams.entries()#

• Returns:<Iterator>

Returns an ES6Iterator over each of the name-value pairs in the query.Each item of the iterator is a JavaScriptArray. The first item of theArrayis thename, the second item of theArray is thevalue.

Alias forurlSearchParams[Symbol.iterator]().

urlSearchParams.forEach(fn[, thisArg])#

• fn<Function> Invoked for each name-value pair in the query
• thisArg<Object> To be used asthis value for whenfn is called

Iterates over each name-value pair in the query and invokes the given function.

const myURL =newURL('https://example.org/?a=b&c=d');myURL.searchParams.forEach((value, name, searchParams) => {console.log(name, value, myURL.searchParams === searchParams);});// Prints://   a b true//   c d truecopy

urlSearchParams.get(name)#

• name<string>
• Returns:<string> |<null> A string ornull if there is no name-value pairwith the givenname.

Returns the value of the first name-value pair whose name isname. If thereare no such pairs,null is returned.

urlSearchParams.getAll(name)#

• name<string>
• Returns:<string[]>

Returns the values of all name-value pairs whose name isname. If there areno such pairs, an empty array is returned.

urlSearchParams.has(name[, value])#

• name<string>
• value<string>
• Returns:<boolean>

Checks if theURLSearchParams object contains key-value pair(s) based onname and an optionalvalue argument.

Ifvalue is provided, returnstrue when name-value pair withsamename andvalue exists.

Ifvalue is not provided, returnstrue if there is at least one name-valuepair whose name isname.

urlSearchParams.keys()#

• Returns:<Iterator>

Returns an ES6Iterator over the names of each name-value pair.

const params =newURLSearchParams('foo=bar&foo=baz');for (const nameof params.keys()) {console.log(name);}// Prints://   foo//   foocopy

urlSearchParams.set(name, value)#

• name<string>
• value<string>

Sets the value in theURLSearchParams object associated withname tovalue. If there are any pre-existing name-value pairs whose names arename,set the first such pair's value tovalue and remove all others. If not,append the name-value pair to the query string.

const params =newURLSearchParams();params.append('foo','bar');params.append('foo','baz');params.append('abc','def');console.log(params.toString());// Prints foo=bar&foo=baz&abc=defparams.set('foo','def');params.set('xyz','opq');console.log(params.toString());// Prints foo=def&abc=def&xyz=opqcopy

urlSearchParams.size#

The total number of parameter entries.

urlSearchParams.sort()#

Sort all existing name-value pairs in-place by their names. Sorting is donewith astable sorting algorithm, so relative order between name-value pairswith the same name is preserved.

This method can be used, in particular, to increase cache hits.

const params =newURLSearchParams('query[]=abc&type=search&query[]=123');params.sort();console.log(params.toString());// Prints query%5B%5D=abc&query%5B%5D=123&type=searchcopy

urlSearchParams.toString()#

• Returns:<string>

Returns the search parameters serialized as a string, with characterspercent-encoded where necessary.

urlSearchParams.values()#

• Returns:<Iterator>

Returns an ES6Iterator over the values of each name-value pair.

urlSearchParams[Symbol.iterator]()#

• Returns:<Iterator>

Returns an ES6Iterator over each of the name-value pairs in the query string.Each item of the iterator is a JavaScriptArray. The first item of theArrayis thename, the second item of theArray is thevalue.

Alias forurlSearchParams.entries().

const params =newURLSearchParams('foo=bar&xyz=baz');for (const [name, value]of params) {console.log(name, value);}// Prints://   foo bar//   xyz bazcopy

urlObject.auth#

Theauth property is the username and password portion of the URL, alsoreferred to asuserinfo. This string subset follows theprotocol anddouble slashes (if present) and precedes thehost component, delimited by@.The string is either the username, or it is the username and password separatedby:.

For example:'user:pass'.

urlObject.hash#

Thehash property is the fragment identifier portion of the URL including theleading# character.

For example:'#hash'.

urlObject.host#

Thehost property is the full lower-cased host portion of the URL, includingtheport if specified.

For example:'sub.example.com:8080'.

urlObject.hostname#

Thehostname property is the lower-cased host name portion of thehostcomponentwithout theport included.

For example:'sub.example.com'.

urlObject.href#

Thehref property is the full URL string that was parsed with both theprotocol andhost components converted to lower-case.

For example:'http://user:pass@sub.example.com:8080/p/a/t/h?query=string#hash'.

urlObject.path#

Thepath property is a concatenation of thepathname andsearchcomponents.

For example:'/p/a/t/h?query=string'.

No decoding of thepath is performed.

urlObject.pathname#

Thepathname property consists of the entire path section of the URL. Thisis everything following thehost (including theport) and before the startof thequery orhash components, delimited by either the ASCII questionmark (?) or hash (#) characters.

For example:'/p/a/t/h'.

No decoding of the path string is performed.

urlObject.port#

Theport property is the numeric port portion of thehost component.

For example:'8080'.

urlObject.protocol#

Theprotocol property identifies the URL's lower-cased protocol scheme.

For example:'http:'.

urlObject.query#

Thequery property is either the query string without the leading ASCIIquestion mark (?), or an object returned by thequerystring module'sparse() method. Whether thequery property is a string or object isdetermined by theparseQueryString argument passed tourl.parse().

For example:'query=string' or{'query': 'string'}.

If returned as a string, no decoding of the query string is performed. Ifreturned as an object, both keys and values are decoded.

urlObject.search#

Thesearch property consists of the entire "query string" portion of theURL, including the leading ASCII question mark (?) character.

For example:'?query=string'.

No decoding of the query string is performed.

urlObject.slashes#

Theslashes property is aboolean with a value oftrue if two ASCIIforward-slash characters (/) are required following the colon in theprotocol.