W3cubDocs

/Web APIs

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 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

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.

Instance properties

hash

A string containing a '#' followed by the fragment identifier of the URL.

host

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

hostname

A string containing the domain of the URL.

href

A stringifier that returns a string containing the whole URL.

origin Read only

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

password

A string containing the password specified before the domain name.

pathname

A string containing an initial '/' followed by the path of the URL, not including the query string or fragment.

port

A string containing the port number of the URL.

protocol

A string containing the protocol scheme of the URL, including the final ':'.

search

A string 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 string containing the username specified before the domain name.

Static methods

canParse()

Returns a boolean indicating whether or not a URL defined from a URL string and optional base URL string is parsable and valid.

createObjectURL()

Returns a string 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().

Instance methods

toString()

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

toJSON()

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

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:

js

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

The constructor will raise an exception if the URL cannot be parsed to a valid URL. You can either call the above code in a try...catch block or use the canParse() static method to first check the URL is valid:

js

if (URL.canParse("../cats", "http://www.example.com/dogs")) {
  const url = new URL("../cats", "http://www.example.com/dogs");
  console.log(url.hostname); // "www.example.com"
  console.log(url.pathname); // "/cats"
} else {
  console.log("Invalid URL"); //Invalid URL
}

URL properties can be set to construct the URL:

js

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:

js

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:

js

// 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.

js

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

Specifications

Specification
URL Standard
# api

Browser compatibility

Desktop Mobile
Chrome Edge Firefox Internet Explorer Opera Safari WebView Android Chrome Android Firefox for Android Opera Android Safari on IOS Samsung Internet
URL 19
12Before Edge 79, query arguments in the base URL argument are removed when calling the URL constructor.
26 No 15 14.1
6In 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.
4.4 25 26 14 14.5
6In 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.
1.5
URL 3219 12
19Before version 57, Firefox had a bug whereby single quotes contained in URLs are escaped when accessed via URL APIs (see bug 1386683).
10 1915 76 4.44 3225
19Before version 57, Firefox had a bug whereby single quotes contained in URLs are escaped when accessed via URL APIs (see bug 1386683).
1914 76 2.01.5
canParse_static No No 115 No No 17 No No 115 No 17 No
createObjectURL_static 19 12
19createObjectURL() is no longer available within the context of a ServiceWorker.
10If 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.
15 6 4.4 25
19createObjectURL() is no longer available within the context of a ServiceWorker.
14 6 1.5
hash 32 13 22 No 19 7 4.4.3 32 22 19 7 2.0
host 32 13 22 No 19 7 4.4.3 32 22 19 7 2.0
hostname 32 13 22 No 19 10 4.4.3 32 22 19 10 2.0
href 32 13 22 No 19 10 4.4.3 32 22 19 10 2.0
origin 32 12 26
26–49Results for URL using the blob scheme incorrectly returned null.
No 19 10 4.4.3 32 26
26–49Results for URL using the blob scheme incorrectly returned null.
19 10 6.0
password 32 12 26 No 19 10 4.4.3 32 26 19 10 6.0
pathname 32 13
22Before Firefox 53, pathname and search returned wrong values for custom protocols. Given protocol:host/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. See bug 1310483.
No 19 10 4.4.3 32
22Before Firefox 53, pathname and search returned wrong values for custom protocols. Given protocol:host/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. See bug 1310483.
19 10 2.0
port 32 13 22 No 19 10 4.4.3 32 22 19 10 2.0
protocol 32 13 22 No 19 10 4.4.3 32 22 19 10 2.0
revokeObjectURL_static 19 12
19revokeObjectURL() is no longer available within the context of a ServiceWorker.
10 15 6 4.4 25
19revokeObjectURL() is no longer available within the context of a ServiceWorker.
14 6 1.5
search 32 13
22Before Firefox 53, pathname and search returned wrong values for custom protocols. Given protocol:host/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. See bug 1310483.
No 19 10 4.4.3 32
22Before Firefox 53, pathname and search returned wrong values for custom protocols. Given protocol:host/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. See bug 1310483.
19 10 2.0
searchParams 51 17 29 No 38 10.1 51 51 29 41 10.3 5.0
toJSON 71 17 54 No 58 11 71 71 54 50 11 10.0
toString 19 17 54 No 15 7 4.4 25 54 14 7 6.0
username 32 12 26 No 19 10 4.4.3 32 26 19 10 6.0

See also

© 2005–2023 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/URL