This is an experimental technology
Because this technology's specification has not stabilized, check the compatibility table for usage in various browsers. Also note that the syntax and behavior of an experimental technology is subject to change in future versions of browsers as the specification changes.
The URL
interface represent 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 host, that is the hostname, 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
- 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 |
In Development[5] | 4.0 (2.0)[1][3] 19.0 (19.0) |
No support[4] | 15.0[2] 19 |
6.0[2] 7.0 |
username , password , and origin |
52 | ? | 26.0 (26.0) | ? | 19 | (Yes) |
searchParams |
51 | ? | 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] 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] Edge in development: see https://developer.microsoft.com/en-us/microsoft-edge/platform/status/urlapi/ and https://wpdev.uservoice.com/forums/257854-microsoft-edge-developer/suggestions/6263638-url-api
See also
- Property allowing to get such an object:
Window.URL
. URLSearchParams
.- Components.utils.importGlobalProperties