The URL
interface is used to parse, construct, normalize, and encode URLs. It works by providing properties which allow you to easily read and modify the components of a URL. You normally create a new URL
object by specifying the URL as a string when calling its constructor, or by providing a relative URL and a base URL. You can then easily read the parsed components of the URL or make changes to the URL.
If a browser doesn't yet support the URL()
constructor, you can access a URL object using the Window
interface's Window.URL
property. Be sure to check to see if any of your target browsers require this to be prefixed.
Constructor
new URL()
- Creates and returns a
URL
object referencing the URL specified using an absolute URL string, or a relative URL string and a base URL string.
Properties
hash
- A
USVString
containing a'#'
followed by the fragment identifier of the URL. host
- A
USVString
containing the domain (that is the hostname) followed by (if a port was specified) a':'
and the port of the URL. hostname
- A
USVString
containing the domain of the URL. href
- A stringifier that returns a
USVString
containing the whole URL. origin
Read only- Returns a
USVString
containing the origin of the URL, that is its scheme, its domain and its port. password
- A
USVString
containing the password specified before the domain name. pathname
- A
USVString
containing an initial'/'
followed by the path of the URL. port
- A
USVString
containing the port number of the URL. protocol
- A
USVString
containing the protocol scheme of the URL, including the final':'
. search
- A
USVString
indicating the URL's parameter string; if any parameters are provided, this string includes all of them, beginning with the leading?
character. searchParams
Read only- A
URLSearchParams
object which can be used to access the individual query parameters found insearch
. username
- A
USVString
containing the username specified before the domain name.
Methods
toString()
- Returns a
USVString
containing the whole URL. It is a synonym forURL.href
, though it can't be used to modify the value. toJSON()
- Returns a
USVString
containing the whole URL. It returns the same string as thehref
property.
Static methods
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. revokeObjectURL()
- Revokes an object URL previously created using
URL.createObjectURL()
.
Usage notes
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 are encoded according to the rules found in RFC 3986. For instance:
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 const parsedUrl = new URL(window.location.href); console.log(parsedUrl.searchParams.get("id")); // "123"
The toString()
method of URL
just returns the value of the href
property, so the constructor can be used to normalize and encode a URL directly.
const response = await fetch(new URL('http://www.example.com/démonstration.html'));
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
Desktop | Mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
URL | Chrome
Full support
32
| Edge Full support 12 | Firefox
Full support
19
| IE Full support 10 | Opera
Full support
19
| Safari
Full support
7
| WebView Android
Full support
4.4
| Chrome Android
Full support
32
| Firefox Android
Full support
19
| Opera Android
Full support
19
| Safari iOS
Full support
7
| Samsung Internet Android
Full support
2.0
|
URL() constructor | Chrome Full support 19 | Edge Full support 12 | Firefox Full support 26 | IE No support No | Opera Full support 15 | Safari Full support 6 | WebView Android Full support ≤37 | Chrome Android Full support 25 | Firefox Android Full support 26 | Opera Android Full support 14 | Safari iOS Full support 6 | Samsung Internet Android Full support 1.5 |
createObjectURL | Chrome Full support 19 | Edge Full support 12 | Firefox
Full support
19
| IE
Full support
10
| Opera Full support 15 | Safari Full support 6 | WebView Android Full support Yes | Chrome Android Full support 25 | Firefox Android
Full support
19
| Opera Android Full support 14 | Safari iOS Full support 6 | Samsung Internet Android Full support 1.5 |
hash | Chrome Full support Yes | Edge Full support 13 | Firefox Full support 22 | IE No support No | Opera Full support Yes | Safari Full support Yes | WebView Android Full support Yes | Chrome Android Full support Yes | Firefox Android Full support 22 | Opera Android Full support Yes | Safari iOS Full support Yes | Samsung Internet Android Full support Yes |
host | Chrome Full support Yes | Edge Full support 13 | Firefox Full support 22 | IE No support No | Opera Full support Yes | Safari Full support Yes | WebView Android Full support Yes | Chrome Android Full support Yes | Firefox Android Full support 22 | Opera Android Full support Yes | Safari iOS Full support Yes | Samsung Internet Android Full support Yes |
hostname | Chrome Full support Yes | Edge Full support 13 | Firefox Full support 22 | IE No support No | Opera Full support Yes | Safari Full support 10 | WebView Android Full support Yes | Chrome Android Full support Yes | Firefox Android Full support 22 | Opera Android Full support Yes | Safari iOS Full support Yes | Samsung Internet Android Full support Yes |
href | Chrome Full support Yes | Edge Full support 13 | Firefox Full support 22 | IE No support No | Opera Full support Yes | Safari Full support 10 | WebView Android Full support Yes | Chrome Android Full support Yes | Firefox Android Full support 22 | Opera Android Full support Yes | Safari iOS Full support Yes | Samsung Internet Android Full support Yes |
origin | Chrome Full support 32 | Edge Full support 12 | Firefox
Full support
26
| IE No support No | Opera Full support Yes | Safari Full support 10 | WebView Android Full support ≤37 | Chrome Android Full support 32 | Firefox Android
Full support
26
| Opera Android Full support Yes | Safari iOS Full support Yes | Samsung Internet Android Full support 6.0 |
password | Chrome Full support 32 | Edge Full support 12 | Firefox Full support 26 | IE No support No | Opera Full support Yes | Safari Full support 10 | WebView Android Full support ≤37 | Chrome Android Full support 32 | Firefox Android Full support 26 | Opera Android Full support Yes | Safari iOS Full support Yes | Samsung Internet Android Full support 6.0 |
pathname | Chrome Full support Yes | Edge Full support 13 | Firefox
Full support
53
| IE No support No | Opera Full support Yes | Safari Full support 10 | WebView Android Full support Yes | Chrome Android Full support Yes | Firefox Android
Full support
53
| Opera Android Full support Yes | Safari iOS Full support Yes | Samsung Internet Android Full support Yes |
port | Chrome Full support Yes | Edge Full support 13 | Firefox Full support 22 | IE No support No | Opera Full support Yes | Safari Full support 10 | WebView Android Full support Yes | Chrome Android Full support Yes | Firefox Android Full support 22 | Opera Android Full support Yes | Safari iOS Full support Yes | Samsung Internet Android Full support Yes |
protocol | Chrome Full support Yes | Edge Full support 13 | Firefox Full support 22 | IE No support No | Opera Full support Yes | Safari Full support 10 | WebView Android Full support Yes | Chrome Android Full support Yes | Firefox Android Full support 22 | Opera Android Full support Yes | Safari iOS Full support Yes | Samsung Internet Android Full support Yes |
revokeObjectURL | Chrome Full support 19 | Edge Full support 12 | Firefox
Full support
19
| IE Full support 10 | Opera Full support 15 | Safari Full support 6 | WebView Android Full support ≤37 | Chrome Android Full support 25 | Firefox Android
Full support
19
| Opera Android Full support 14 | Safari iOS Full support 6 | Samsung Internet Android Full support 1.5 |
search | Chrome Full support Yes | Edge Full support 13 | Firefox
Full support
53
| IE No support No | Opera Full support Yes | Safari Full support 10 | WebView Android Full support Yes | Chrome Android Full support Yes | Firefox Android
Full support
53
| Opera Android Full support Yes | Safari iOS Full support Yes | Samsung Internet Android Full support Yes |
searchParams | Chrome Full support 51 | Edge Full support 17 | Firefox Full support 29 | IE No support No | Opera Full support 38 | Safari Full support 10 | WebView Android Full support 51 | Chrome Android Full support 51 | Firefox Android Full support 29 | Opera Android Full support 41 | Safari iOS Full support 10 | Samsung Internet Android Full support 5.0 |
toJSON | Chrome Full support 71 | Edge Full support 17 | Firefox Full support 54 | IE No support No | Opera Full support Yes | Safari Full support Yes | WebView Android Full support 71 | Chrome Android Full support 71 | Firefox Android Full support 54 | Opera Android Full support Yes | Safari iOS Full support Yes | Samsung Internet Android Full support 10.0 |
toString | Chrome Full support 19 | Edge Full support 17 | Firefox Full support 54 | IE No support No | Opera Full support Yes | Safari Full support Yes | WebView Android Full support ≤37 | Chrome Android Full support 25 | Firefox Android Full support 54 | Opera Android Full support Yes | Safari iOS Full support Yes | Samsung Internet Android Full support 6.0 |
username | Chrome Full support 32 | Edge Full support 12 | Firefox Full support 26 | IE No support No | Opera Full support Yes | Safari Full support 10 | WebView Android Full support ≤37 | Chrome Android Full support 32 | Firefox Android Full support 26 | Opera Android Full support Yes | Safari iOS Full support Yes | Samsung Internet Android Full support 6.0 |
Legend
- Full support
- Full support
- No support
- No support
- Experimental. Expect behavior to change in the future.
- Experimental. Expect behavior to change in the future.
- See implementation notes.
- See implementation notes.
- Requires a vendor prefix or different name for use.
- Requires a vendor prefix or different name for use.
See also
- URL API
- What is a URL?
- Property to obtain a
URL
object:Window.URL
. URLSearchParams
.