URL

The URL interface represents an object providing static methods used for creating object URLs.

When using a user agent where no constructor has been implemented yet, it is possible to access such an object using the Window.URL properties (prefixed with Webkit-based browser as Window.webkitURL).

Usage

URL is used to parse, construct, normalise, and encode URLs.

The constructor takes a url parameter, and an optional base parameter to use as a base if the url parameter is a relative URL:

const url = new URL('../cats', 'http://www.example.com/dogs');
console.log(url.hostname); // "www.example.com"
console.log(url.pathname); // "/cats"

URL properties can be set to construct the URL:

url.hash = 'tabby';
console.log(url.href); // "http://www.example.com/cats#tabby"

URLs will be encoded as per RFC 3986:

url.pathname = 'démonstration.html';
console.log(url.href); // "http://www.example.com/d%C3%A9monstration.html"

The URLSearchParams interface can be used to build and manipulate the URL query string.

To get the search params from the current window's URL, you can do this:

// https://some.site/?id=123
var parsedUrl = new URL(window.location.href);
console.log(parsedUrl.searchParams.get("id")); // 123

The stringifier method of URL is the href property, so the constructor can be used to normalise and encode a URL directly.

const response = await fetch(new URL('http://www.example.com/démonstration.html'));

Constructor

URL()

Creates and return a URL object composed from the given parameters.

Properties

URL.hash

Is a DOMString containing a '#' followed by the fragment identifier of the URL.

URL.host

Is a DOMString containing the domain (that is the hostname) followed by (if a port was specified) a ':' and the port of the URL.

URL.hostname

Is a DOMString containing the domain of the URL.

URL.href

Is a DOMString containing the whole URL.

URL.origin Read only

Returns a DOMString containing the origin of the URL, that is its scheme, its domain and its port.

URL.password

Is a DOMString containing the password specified before the domain name.

URL.pathname

Is a DOMString containing an initial '/' followed by the path of the URL.

URL.port

Is a DOMString containing the port number of the URL.

URL.protocol

Is a DOMString containing the protocol scheme of the URL, including the final ':'.

URL.search

Is a DOMString containing a '?' followed by the parameters of the URL.

URL.searchParams Read only

Returns a URLSearchParams object allowing to access the GET query arguments contained in the URL.

URL.username

Is a DOMString containing the username specified before the domain name.

Methods

The URL interface implements methods defined in URLUtils.

URLUtils.toString()

Returns a DOMString containing the whole URL. It is a synonym for URLUtils.href, though it can't be used to modify the value.

URL.toJSON() ^{[available since FireFox v54]}

Returns a DOMString containing the whole URL. It returns the same string as the href property.

Static methods

URL.createObjectURL()

Returns a DOMString containing a unique blob URL, that is a URL with blob: as its scheme, followed by an opaque string uniquely identifying the object in the browser.

URL.revokeObjectURL()

Revokes an object URL previously created using URL.createObjectURL().

Specifications

Browser compatibility

[1] From Gecko 2 (Firefox 4) to Gecko 18 included, Gecko supported this interface with the non-standard nsIDOMMozURLProperty internal type. As the only to access such an object was through window.URL, in practice, this didn't make any difference.

[2] This feature is implemented under the non-standard name webkitURL.

[3] For Firefox, to use from chrome code, JSM and Bootstrap scope, you have to import it like this:

Cu.importGlobalProperties(['URL']);

URL is available in Worker scopes.

[4] As of IE11, instantiating new URL objects is not supported - ie. new URL() does not work.

[5] see status of URL API in Microsoft Edge, API Catalog of Microsoft Edge and https://wpdev.uservoice.com/forums/257854-microsoft-edge-developer/suggestions/6263638-url-api.

[6] Firefox has a bug whereby single quotes contained in URLs are escaped when accessed via URL APIs (bug 1386683). This has been fixed as of Firefox 57.

See also

• Property allowing to get such an object: Window.URL.
• URLSearchParams.
• Components.utils.importGlobalProperties