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.
Browser support
| Feature | Desktop | Mobile | ||||
|---|---|---|---|---|---|---|
| Chrome | Edge | Firefox | Safari | Chrome Android | Safari iOS | |
| 32 | 12 | 19 | 7 | 32 | 7 | |
| The hash property of the URL interface is a string containing a "#" followed by the fragment identifier of the URL. If the URL does not have a fragment identifier, this property contains an empty string, "". | 32 | 13 | 22 | 7 | 32 | 7 |
| The host property of the URL interface is a string containing the host, which is the URL.hostname, and then, if the port of the URL is nonempty, a ":", followed by the URL.port of the URL. If the URL does not have a hostname, this property contains an empty string, "". | 32 | 13 | 22 | 7 | 32 | 7 |
| The hostname property of the URL interface is a string containing either the domain name or IP address of the URL. If the URL does not have a hostname, this property contains an empty string, "". IPv4 and IPv6 addresses are normalized, such as stripping leading zeros, and domain names are converted to IDN. | 32 | 13 | 22 | 10 | 32 | 10 |
| The href property of the URL interface is a string containing the whole URL. | 32 | 13 | 22 | 10 | 32 | 10 |
| The origin read-only property of the URL interface returns a string containing the Unicode serialization of the origin of the represented URL. | 32 | 12 | 26 | 10 | 32 | 10 |
| The URL.parse() static method of the URL interface returns a newly created URL object representing the URL defined by the parameters. | 126 | 126 | 126 | 18 | 126 | 18 |
| The password property of the URL interface is a string containing the password component of the URL. If the URL does not have a password, this property contains an empty string, "". | 32 | 12 | 26 | 10 | 32 | 10 |
| The pathname property of the URL interface represents a location in a hierarchical structure. It is a string constructed from a list of path segments, each of which is prefixed by a / character. | 32 | 13 | 22 | 10 | 32 | 10 |
| The port property of the URL interface is a string containing the port number of the URL. If the port is the default for the protocol (80 for ws: and http:, 443 for wss: and https:, and 21 for ftp:), this property contains an empty string, "". | 32 | 13 | 22 | 10 | 32 | 10 |
| The protocol property of the URL interface is a string containing the protocol or scheme of the URL, including the final ":". | 32 | 13 | 22 | 10 | 32 | 10 |
| The search property of the URL interface is a search string, also called a query string, that is a string containing a "?" followed by the parameters of the URL. If the URL does not have a search query, this property contains an empty string, "". | 32 | 13 | 22 | 10 | 32 | 10 |
| The searchParams read-only property of the URL interface returns a URLSearchParams object allowing access to the GET decoded query arguments contained in the URL. | 51 | 17 | 29 | 10.1 | 51 | 10.3 |
| The toJSON() method of the URL interface returns a string containing a serialized version of the URL, although in practice it seems to have the same effect as URL.toString(). | 71 | 17 | 54 | 11 | 71 | 11 |
| The toString() method of the URL interface returns a string containing the whole URL. It is effectively a read-only version of URL.href. | 19 | 17 | 54 | 7 | 25 | 7 |
| The URL() constructor returns a newly created URL object representing the URL defined by the parameters. | 19 | 12 | 26 | 14.1 | 25 | 14.5 |
| The username property of the URL interface is a string containing the username component of the URL. If the URL does not have a username, this property contains an empty string, "". | 32 | 12 | 26 | 10 | 32 | 10 |
| The URLSearchParams interface defines utility methods to work with the query string of a URL. | 49 | 17 | 29 | 10.1 | 49 | 10.3 |
@@iterator [Symbol.iterator] | 49 | 17 | 44 | 10.1 | 49 | 10.3 |
| The append() method of the URLSearchParams interface appends a specified key/value pair as a new search parameter. | 49 | 17 | 29 | 10.1 | 49 | 10.3 |
| The delete() method of the URLSearchParams interface deletes specified parameters and their associated value(s) from the list of all search parameters. | 49 | 17 | 29 | 14 | 49 | 14 |
delete (value parameter) `value` parameter | 117 | 117 | 115 | 17 | 117 | 17 |
| The entries() method of the URLSearchParams interface returns an Iteration_protocols allowing iteration through all key/value pairs contained in this object. The iterator returns key/value pairs in the same order as they appear in the query string. The key and value of each pair are strings. | 49 | 17 | 44 | 10.1 | 49 | 10.3 |
| The forEach() method of the URLSearchParams interface allows iteration through all values contained in this object via a callback function. | 49 | 17 | 44 | 10.1 | 49 | 10.3 |
| The get() method of the URLSearchParams interface returns the first value associated to the given search parameter. | 49 | 17 | 29 | 10.1 | 49 | 10.3 |
| The getAll() method of the URLSearchParams interface returns all the values associated with a given search parameter as an array. | 49 | 17 | 29 | 10.1 | 49 | 10.3 |
| The has() method of the URLSearchParams interface returns a boolean value that indicates whether the specified parameter is in the search parameters. | 49 | 17 | 29 | 10.1 | 49 | 10.3 |
has (value parameter) `value` parameter | 117 | 117 | 115 | 17 | 117 | 17 |
| The keys() method of the URLSearchParams interface returns an Iteration_protocols allowing iteration through all keys contained in this object. The keys are strings. | 49 | 17 | 44 | 10.1 | 49 | 10.3 |
| The set() method of the URLSearchParams interface sets the value associated with a given search parameter to the given value. If there were several matching values, this method deletes the others. If the search parameter doesn't exist, this method creates it. | 49 | 17 | 29 | 10.1 | 49 | 10.3 |
| The size read-only property of the URLSearchParams interface indicates the total number of search parameter entries. | 113 | 113 | 112 | 17 | 113 | 17 |
| The URLSearchParams.sort() method sorts all key/value pairs contained in this object in place and returns undefined. Key/value pairs are sorted by the values of the UTF-16 of the keys. This method uses a stable sorting algorithm (i.e., the relative order between key/value pairs with equal keys will be preserved). | 61 | 17 | 54 | 11 | 61 | 11 |
| The toString() method of the URLSearchParams interface returns a query string suitable for use in a URL. | 49 | 17 | 29 | 10.1 | 49 | 10.3 |
| The URLSearchParams() constructor creates and returns a new URLSearchParams object. | 49 | 17 | 29 | 10.1 | 49 | 10.3 |
URLSearchParams (record) record for `init` object | 61 | 17 | 54 | 11 | 61 | 11 |
URLSearchParams (sequence) sequence for `init` object | 58 | 17 | 53 | 11 | 58 | 11 |
URLSearchParams (USVString) `USVString` for `init` object | 49 | 17 | 29 | 10.1 | 49 | 10.3 |
| The values() method of the URLsearchParams interface returns an Iteration_protocols allowing iteration through all values contained in this object. The values are strings. | 49 | 17 | 44 | 10.1 | 49 | 10.3 |
- Available with a vendor prefix: webkit (19)
- Before version 57, Firefox had a bug whereby single quotes contained in URLs are escaped when accessed via URL APIs (see bug 1386683).
- Available with a vendor prefix: webkit (6)
- Available with a vendor prefix: webkit (25)
- Available with a vendor prefix: webkit (6)
- Before Firefox 49, Results for `URL` using the `blob` scheme incorrectly returned `null`.
- Before 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.
- Before 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.
- Before Edge 79, query arguments in the base URL argument are removed when calling the `URL` constructor.
- Before version 122, `host`, `hostname`, and `port` were not parsed for unknown protocols/schemes.
- This browser only partially implements this feature
- This feature was removed in a later browser version (14.1)
- Before Safari 14.1, calling the `URL` constructor with a base URL whose value is `undefined` caused Safari to throw a `TypeError`, see bug 216841.
- This browser only partially implements this feature
- This feature was removed in a later browser version (14.5)
- Before Safari on iOS 14.1, calling the `URL` constructor with a base URL whose value is `undefined` caused Safari on iOS to throw a `TypeError`, see bug 216841.
- Before version 57 single quotes in URLs were escaped (see bug 1386683).
- This browser only partially implements this feature
- This feature was removed in a later browser version (14)
- Removing a non-existent query parameter doesn't remove `?` from the URL. See bug 193022.
- This browser only partially implements this feature
- This feature was removed in a later browser version (14)
- Removing a non-existent query parameter doesn't remove `?` from the URL. See bug 193022.
Syntax
const url = new URL("cats", "http://www.example.com/animals/dogs");
console.log(url.hostname); // "www.example.com"
console.log(url.pathname); // "/animals/cats" Use cases
-
Using URL
The URL interface is used to parse, construct, normalize, and encode URLs.
Cautions
- May not be supported in older browsers.
Implementation notes
- Some APIs require a secure context (HTTPS) or user activation. Check the requirements before use.