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 forURLUtils.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 thehref
property.
Static methods
URL.createObjectURL()
- Returns a
DOMString
containing a unique blob URL, that is a URL withblob:
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
Specification | Status | Comment |
---|---|---|
File API The definition of 'URL' in that specification. |
Working Draft | Added the static methods URL.createObjectURL() and URL.revokeObjectURL () . |
URL The definition of 'API' in that specification. |
Living Standard | Initial definition (implements URLUtils ). |
Browser compatibility
Feature | Chrome | Edge | Firefox (Gecko) | Internet Explorer | Opera | Safari |
---|---|---|---|---|---|---|
Basic support | 8.0[2] 32 |
10240[5] |
4.0 (2.0)[1][3][6] 19.0 (19.0) |
No support[4] | 15.0[2] 19 |
6.0[2] 7.0 |
username , password , and origin |
52 | 10240 | 26.0 (26.0) | ? | 19 | (Yes) |
searchParams |
51 | No support[5] | 29.0 (29.0) | ? | 36 | No support |
toJSON |
? | ? | 54 (54) | ? | ? | ? |
Feature | Android Webview | Chrome for Android | Firefox Mobile (Gecko) | IE Mobile | Opera Mobile | Safari Mobile |
---|---|---|---|---|---|---|
Basic support | 4[2] 4.4 |
8.0[2] 32 |
14.0 (14.0)[1][3][6] 19.0 (19.0) |
(Yes) | 15.0[2] | 6.0[2] |
username , password , and origin |
52 | 52 | 26.0 (26.0) | ? | ? | (Yes) |
searchParams |
51 | 51 | 29.0 (29.0) | ? | ? | ? |
[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