Web/API/URL

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.

Note: This feature is available in Web Workers.

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: Is a USVString containing an initial '/' followed by the path of the URL, not including the query string or fragment.
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 in search.
username: A USVString containing the username specified before the domain name.

Methods

toString(): Returns a USVString containing the whole URL. It is a synonym for URL.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 the href property.

Static methods

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.
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 APIThe definition of 'URL' in that specification.	Working Draft	Added the static methods `URL.createObjectURL()` and `URL.revokeObjectURL()`.
URLThe definition of 'API' in that specification.	Living Standard	Initial definition (implements `URLUtils`).

Browser compatibility

Update compatibility data on GitHub

	Desktop						Mobile
	Chrome	Edge	Firefox	Internet Explorer	Opera	Safari	Android webview	Chrome for Android	Firefox for Android	Opera for Android	Safari on iOS	Samsung Internet
`URL`	Chrome Full support 32 Full support 32 Full support 19 Prefixed' Prefixed' Implemented with the vendor prefix: webkit	Edge Full support 12	Firefox Full support 19 Notes' Full support 19 Notes' Notes' Before version 57, Firefox had a bug whereby single quotes contained in URLs are escaped when accessed via URL APIs (see bug 1386683). Notes' To use it from chrome code, JSM and Bootstrap scope, you have to import it with `Cu.importGlobalProperties(['URL']);`.	IE Full support 10	Opera Full support 19 Full support 19 Full support 15 Prefixed' Prefixed' Implemented with the vendor prefix: webkit	Safari Full support 7 Full support 7 Full support 6 Prefixed' Prefixed' Implemented with the vendor prefix: webkit	WebView Android Full support 4.4 Full support 4.4 Full support 4 Prefixed' Prefixed' Implemented with the vendor prefix: webkit	Chrome Android Full support 32 Full support 32 Full support 25 Prefixed' Prefixed' Implemented with the vendor prefix: webkit	Firefox Android Full support 19 Notes' Full support 19 Notes' Notes' Before version 57, Firefox had a bug whereby single quotes contained in URLs are escaped when accessed via URL APIs (see bug 1386683). Notes' To use it from chrome code, JSM and Bootstrap scope, you have to import it with `Cu.importGlobalProperties(['URL']);`.	Opera Android Full support 19 Full support 19 Full support 14 Prefixed' Prefixed' Implemented with the vendor prefix: webkit	Safari iOS Full support 7 Full support 7 Full support 6 Prefixed' Prefixed' Implemented with the vendor prefix: webkit	Samsung Internet Android Full support 2.0 Full support 2.0 Full support 1.5 Prefixed' Prefixed' Implemented with the vendor prefix: webkit
`URL()` constructor	Chrome Full support 19	Edge Full support 12	Firefox Full support 26	IE No support No	Opera Full support 15	Safari Partial support 6 Notes' Partial support 6 Notes' Notes' In Safari 14 and earlier, calling the `URL` constructor with a base URL whose value is `undefined` causes Safari to throw a `TypeError`; see WebKit bug 216841.	WebView Android Full support ≤37	Chrome Android Full support 25	Firefox Android Full support 26	Opera Android Full support 14	Safari iOS Partial support 6 Notes' Partial support 6 Notes' Notes' In Safari 14 and earlier, calling the `URL` constructor with a base URL whose value is `undefined` causes Safari to throw a `TypeError`; see WebKit bug 216841.	Samsung Internet Android Full support 1.5
`createObjectURL` Experimental'	Chrome Full support 19	Edge Full support 12	Firefox Full support 19 Notes' Full support 19 Notes' Notes' `createObjectURL()` is no longer available within the context of a `ServiceWorker`.	IE Full support 10 Notes' Full support 10 Notes' Notes' If the underlying object does not have a content type set, using this URL as the `src` of an `img` tag fails intermittently with error DOM7009.	Opera Full support 15	Safari Full support 6	WebView Android Full support Yes	Chrome Android Full support 25	Firefox Android Full support 19 Notes' Full support 19 Notes' Notes' `createObjectURL()` is no longer available within the context of a `ServiceWorker`.	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 Full support 26 No support 26 — 49 Notes' Notes' Results for `URL` using the `blob` scheme incorrectly returned `null`.	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 Full support 26 No support 26 — 49 Notes' Notes' Results for `URL` using the `blob` scheme incorrectly returned `null`.	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 Full support 53 No support 22 — 53 Notes' Notes' `pathname` and `search` returned the wrong values so that for a URL of `http://z.com/x?a=true&b=false`, `pathname` would return "/x?a=true&b=false" and `search` would return "", rather than "/x" and "?a=true&b=false" respectively.	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 Full support 53 No support 22 — 53 Notes' Notes' `pathname` and `search` returned the wrong values so that for a URL of `http://z.com/x?a=true&b=false`, `pathname` would return "/x?a=true&b=false" and `search` would return "", rather than "/x" and "?a=true&b=false" respectively.	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` Experimental'	Chrome Full support 19	Edge Full support 12	Firefox Full support 19 Notes' Full support 19 Notes' Notes' `revokeObjectURL()` is no longer available within the context of a `ServiceWorker`.	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 Notes' Full support 19 Notes' Notes' `revokeObjectURL()` is no longer available within the context of a `ServiceWorker`.	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 Full support 53 No support 22 — 53 Notes' Notes' `pathname` and `search` returned the wrong values so that for a URL of `http://z.com/x?a=true&b=false`, `pathname` would return "/x?a=true&b=false" and `search` would return "", rather than "/x" and "?a=true&b=false" respectively.	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 Full support 53 No support 22 — 53 Notes' Notes' `pathname` and `search` returned the wrong values so that for a URL of `http://z.com/x?a=true&b=false`, `pathname` would return "/x?a=true&b=false" and `search` would return "", rather than "/x" and "?a=true&b=false" respectively.	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
Partial support: Partial 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.