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

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* Polyfill of `URL` in `core-js`
* URL API
* What is a URL?
* Property to obtain a `URL` object: `URL`.
* `URLSearchParams`.