Use the URL Object in JavaScript for Easy URL Manipulation
Tags: webdev, javascript, tutorial, beginners
Published: 2020-01-12 22:48:31

**Subscribe to my email list now at http://jauyeung.net/subscribe/**

**Follow me on Twitter at https://twitter.com/AuMayeung**

**Many more articles at https://medium.com/@hohanga**

Manipulating and extracting parts from a URL is a pain if we have to write all the code ourselves. Fortunately, most browsers have the URL object built into their standard library. Now, we can pass in the URL, as a string, to the URL constructor and create an instance of it. Then, we can use the handy value properties and methods to manipulate and get the parts of a URL that we want.

To create a URL object with the URL constructor, we use the `new` keyword like in the following code:

```javascript
new URL('http://medium.com');
```

In above code, we create an instance of the URL object with an absolute URL. We can also create a URL object by passing-in a relative URL as the first argument and the base URL as the second argument. For example, we can write:

```javascript
new URL('/@hohanga', 'http://medium.com');
```

Note that the second argument must be a base URL. This means that it must be a valid URL and not just part of it. It must start with the protocol like `http://` or `https://`. We can also define them in a chain-like in the following code:

```javascript
const mozillaUrl = 'https://developer.mozilla.org';  
const mozillaDevUrl = new URL("/", mozillaUrl);  
const mozillaUrl2 = new URL(mozillaUrl);  
const docsUrl = new URL('/en-US/docs', mozillaUrl2);  
const urlUrl = new URL('Web/API/URL', docsUrl);
```

If we call `toString()` on the URL objects above, we should get something like:

```
https://developer.mozilla.org
https://developer.mozilla.org/
https://developer.mozilla.org/
https://developer.mozilla.org/en-US/docs
https://developer.mozilla.org/en-US/Web/API/URL
```

The second argument is an optional argument and it should only be passed in when the first argument is a relative URL. The strings or URL objects that we pass in are converted to `USVString` objects which correspond to the set of all possible sequences of Unicode scalar values. In our code, we can treat them the same as regular strings. A `TypeError` will be thrown if both argument are relative URLs or if the base and the relative URL together aren’t valid. We can pass in the URL object directly to the second argument because the `toString` method of the URL object will convert a URL object into a full URL string before being manipulated in the constructor.

A URL object can have the following properties. This article will have the first half of the list of properties and Part 2 of this article will have the second half.

Hash Property
=============

The `hash` property has the part of the URL that comes after the pound sign (`#` ). The string isn’t percent decoded, so special symbols like the following are still encoded. They’re encoding with the following mapping. The characters on the left side are converted to the ones on the right side during encoding:

*   `‘:’` — `%3A`
*   `‘/’` — `%2F`
*   `‘?’` — `%3F`
*   `‘#’` — `%23`
*   `‘[‘` — `%5B`
*   `‘]’` — `%5D`
*   `‘@’` — `%40`
*   `‘!’` — `%21`
*   `‘$’` — `%24`
*   `“‘“` — `%27`
*   `‘(‘` — `%28`
*   `‘)’` — `%29`
*   `‘*’` — `%2A`
*   `‘+’` — `%2B`
*   `‘,’` — `%2C`
*   `‘;’` — `%3B`
*   `‘=’` — `%3D`
*   `‘%’` — `%25`
*   `‘ ‘` — `%20` or `+`

For example, if we have the URL `https://example.com#hash` . Then we can extract the hash with the `hash` property as follows:

```javascript
const exampleUrl = new URL('https://example.com#hash');  
console.log(exampleUrl.hash);
```

Then we get `'#hash'` in the `console.log` statement. The property is a `USVString` , but it’s converted to a string when we retrieve it like we did above. This is not a read-only property, so we can also assign to it like in the following code:

```javascript
exampleUrl.hash = '#newHash';
```

For example, if we have:

```javascript
const exampleUrl = new URL('https://example.com#hash');  
exampleUrl.hash = '#newHash';  
console.log(exampleUrl.hash);
```

Then we get `https://example.com/#newHash` as the new URL when we get it with the `href` property.

Host Property
=============

The `host` property of the URL object is a `USVString` that contains the host name. If a port is included after the `:` , then we also get the port number along with the host. For example, if we have:

```javascript
const exampleUrl = new URL('https://example.com:8888');  
console.log(exampleUrl.host);
```

Then we get `example.com:8888` . Like other `USVString` properties, it’s converted to a string when we retrieve it. This is not a read only property, so we can also assign to it like in the following code:

```javascript
exampleUrl.host = 'example.com';
```

We can also set the `host` property to change the URL structure. For example, if we have:

```javascript
const exampleUrl = new URL('https://example.com:8888/en-US/docs/Web/API/URL/href/');
```
`exampleUrl` as the new URL when we get it with the `href` property.

Hostname Property
=================

With the `hostname` property, we can get the host name from the URL as a `USVString`. It will not include the port even if it’s included in the URL string that we used to construct the URL object. For example, if we have:

```javascript
const exampleUrl = new URL('https://example.com:8888'));  
console.log(exampleUrl.hostname);
```

Then we get `example.com` from the `console.log` statement. Like other `USVString` properties, it’s converted to a string when we retrieve it. This is not a read-only property, so we can also assign to it like in the following code:

```javascript
exampleUrl.hostname = ‘newExample.com’;
```

Then we get that the new URL is `https://newexample.com:8888/` when we get it with the `href` property.

Href Property
=============

The `href` property of the URL object is `USVString` that has the whole URL. For example, if we have:

```javascript
const exampleUrl = new URL(‘https://example.com:8888/en-US/docs/Web/API/URL/href/');  
console.log(exampleUrl.href);
```

Then when we run the code above, we get `https://example.com:8888/en-US/docs/Web/API/URL/href/` which is what we passed into the URL constructor. We can also set the `href` property by assigning our own value to it. For example, we can write:

```javascript
const exampleUrl = new URL('https://example.com:8888/en-US/docs/Web/API/URL/href/');  
exampleUrl.href = 'https://newExample.com';  
console.log(exampleUrl.href);
```

Origin Property
===============

The `origin` property is a read-only property that returns a `USVString` with the Unicode serialization of the origin of the URL. The structure of the `origin` will depend on the type of URL that’s used to construct the URL object. For `http` or `https` URLs, the origin will be the protocol followed by `://` , then followed by the domain, then followed by the colon (`:` ), then followed by the port. The default port will only be omitted, which is 80 for `http` and 443 for `https` , if it’s explicitly specified. For `file` protocol URLs, the value will be browser dependent. For `blob:` URLs, the `origin` will be the part following `blob:` . For example, `"blob:http://example.com"` will be returned as `"http://example.com"` . For example, if we have:

```javascript
const url = new URL("https://example.org:443")  
console.log(url.origin);
```

Then we get:

```
https://example.org
```

If we have an `http` URL like the following:

```javascript
const url = new URL("http://example.org:80")  
console.log(url.origin);
```

Then we get:

```
http://example.org
```

If we have a non-default port for `http` or `https` URLs, like in the following:

```javascript
const url = new URL("http://example.org:8888")  
console.log(url.origin);
const url2 = new URL("http://example.org:8888")  
console.log(url.origin);
```

Then we get `http://example.org:8888`  
and `http://example.org:8888` respectively.

If we have a `blob` URL, like in the following:

```javascript
const url = new URL("blob:http://example.org:8888")  
console.log(url.origin);
```

Then we get `http://example.org:8888` . And for `file` URLs like the following:

```javascript
const url = new URL("file://c:/documents/document.docx")  
console.log(url.origin);
```

Then we get `file://` in Chrome.

Password Property
=================

The `password` property is a writable property that extracts the password portion of the URL before the domain name. Like the other properties, the string is a `USVString` . If it’s set without the `username` property being set first, then assigning to this property will silently fail. For example, if we have:

```javascript
const url = new URL('https://username:password@example.com');  
console.log(url.password);
```

Then we get `password` in the `console.log` statement above. We can also set the `password` property to the password of our choice. For example, if we have:

```javascript
const url = new URL('https://username:password@example.com');  
url.password = 'newPassword'  
console.log(url);
```

Then we get `https://username:newPassword@example.com` as the new URL when we get it with the `href` property.

Pathname Property
=================

The `pathname` property is a `USVString` property which has the part following the first slash (`/`). It’s writable property. For example, we can get the `pathname` value from the URL in the following code:

```javascript
const url = new URL('https://example.com/path1/path2');  
console.log(url.pathname);
```

Then we get `/path1/path2` when we run the `console.log` statement above. We can also set the `pathname` property to the relative URL of your choice by setting it to the part after the domain. For example, we can write:

```javascript
const url = new URL('https://example.com/path1/path2');  
url.pathname = '/newpath1/newpath2';  
console.log(url.href);
```

Then we get `https://example.com/newpath1/newpath2` when we run the `console.log` statement above.

Manipulating and extract parts from a URL is a pain if we have to write all the code to do it ourselves. Fortunately, most browsers have the URL object built in to their standard library. Now we can pass in the URL as a string to the URL constructor and to create an instance of a URL. Then we can use the handy value properties and methods to manipulate and get the parts of a URL that we want.

To create an URL object with the URL constructor, we use the `new` keyword like in the following code:

```javascript
new URL('http://medium.com');
```

To see more ways to create an URL object, see Part 1 for more details.

A URL object can have the following properties. This article will have the second half of the list of properties and Part 1 of this article will have the first half. All string values are stored as `USVString`. `USVString` are objects which correspond to the set of all possible sequences of Unicode scalar values. All `USVString` values are converted to strings before we get them, so we can treat them all like regular strings.


Value Properties
================

port Property
-------------

The `port` property is a `USVString` property that has the port number of the URL. For example, if we have:

```javascript
const url = new URL('https://example.com:8888');  
console.log(url.port);
```

Then we get `8888` from the `console.log` statement. We can also set the port to get a new URL with by assigning the `port` property with a new value. For example, if we have the following code:

```javascript
const url = new URL('https://example.com:8888');  
url.port = '3333';  
console.log(url.href);
```

Then we get `https://example.com:3333/` from the `console.log` statement when we run the code above.

protocol Property
-----------------

With the `protocol` property, we can get the the protocol portion of the URL as a `USVString` , which is the very first part of the URL. Example protocols include `http:` , `https:` , `ftp:` , `file:` , etc. For instance, if we have the URL `https://example.com`, then `https` is the protocol portion of the URL. If we have the following code:

```javascript
const url = new URL('https://example.com:8888');  
console.log(url.protocol);
```

Then we get `https:` from the `console.log` statement in the code above.

For other protocols like `ftp` , it also works:

```javascript
const url = new URL('ftp://example.com:8888');  
console.log(url.protocol);
```

If we run the code above, then we get `ftp:` from the `console.log` statement in the code above.

We can also set the `protocol` property to get a new URL. For example, if we have:

```javascript
const url = new URL('ftp://example.com:8888');  
url.protocol = 'http://'
console.log(url.href);
```

Then we get `http://example.com:8888/` from the `console.log` above. It also works if we omit the slashes or omit both the colon and the slashes. For example, if we have:

```javascript
const url = new URL('ftp://example.com:8888');  
url.protocol = 'http:' 
console.log(url.href);
```

Then we also get `http://example.com:8888/` from the `console.log` above. Likewise, if we have:

```javascript
const url = new URL('ftp://example.com:8888');  
url.protocol = 'http'
console.log(url.href);
```

We get the same thing.

search Property
---------------

To get the search string or query string from a URL, we can use the `search` property. The query string is anything after the `?` in a URL. Like all the other properties, this one is also `USVString` property. Note that this property get the whole query string. If you want the individual keys and values from the query string, then we can use the `searchParams` property. We can use the `search` property like the following code:

```javascript
const url = new URL('http://example.com:8888?key1=value1&key2=value2');  
console.log(url.search);
```

Then we get back `?key1=value1&key2=value2` from the `console.log` statement when we run the code above. We can also change the query string of the URL by assigning it a new value. For example, if we have the following code:

```javascript
const url = new URL('http://example.com:8888?key1=value1&key2=value2');  
url.search = 'newKey1=newValue1&newKey2=newValue2';  
console.log(url.href);
```

Then we get `http://example.com:8888/?newKey1=newValue1&newKey2=newValue2` from the `console.log` statement when we run the code above.

searchParams Property
---------------------

The `search` property only gets us the whole query string. To parse the query string into keys and values, we can use the `searchParams` property, which will get us a `URLSearchParams` object which has the list of keys and values listed on the query string. The keys and values will be decoded so that special characters are all intact. This is a read only property so we can’t set the query string directly by assigning a new value to this property. For example, to get the query string as a list of keys and values, we can write the following code:

```javascript
const url = new URL('http://example.com:8888/?key1=value1&key2=value2');  
console.log(url.searchParams.get('key1'));  
console.log(url.searchParams.get('key2'));
```

Then we get `value1` from the first `console.log` statement and `value2` from the second `console.log` statement. The `URLSearchParams` object has a `get` method to get the value of the given query string key by the key name.

Username Property
-----------------

We can get and set the username part of the URL with the `username` property. The username is a URL comes before the password and domain name. For example, if we have the following code:

```javascript
const url = new URL('http://username:password@example.com');  
console.log(url.username);
```

Then when we run the code above, we get `username` from the `console.log` statement above. Also, we can use it to set the username in a URL. For instance, if we have the following code:

```javascript
const url = new URL('http://username:password@example.com');  
url.username = 'newUserName';  
console.log(url.href);
```

Then we get `http://newUserName:password@example.com/` from the `console.log` statement in the code above.

Instance Methods
================

URL object instances also have 2 methods. It has a `toString()` and a `toJSON()` method. The `toString()` method returns a `USVString` containing the whole URL. It’s the same as the `href` property for getting the whole URL, but we can’t use the `toString()` method to set the whole URL like we do with the `href` property. For example, if we have:

```javascript
const url = new URL('http://username:password@example.com');  
console.log(url.toString());
```

Then we get `http://username:password@example.com/` from the `console.log` statement above.

The `toJSON()` method returns a JSON serialized version of the URL object. However, in most cases, it’s actually the same as what `toString()` will return. For example, if we have:

```javascript
const url = new URL('http://username:password@example.com');  
console.log(url.toJSON());  
console.log(url.toString());  
console.log(url.toJSON() === url.toString());
```

Then we get:

```
http://username:password@example.com/
http://username:password@example.com
true
```

from the `console.log` statements when the code above is run. Then `url.toJSON()` and `url.toString()` calls returned the same output, and it’s confirmed by the comparison statement `url.toJSON() === url.toString()` , which evaluated to `true` .

Static Methods
==============

There are 2 static methods in the URL constructor. It has the `createObjectURL()` method and the `revokeObjectURL()` method. The `createObjectURL()` static method creates a `DOMString` containing a URL representing the object given in the parameter. A `DOMString` is a UTF-16 encoded string. Since JavaScript uses UTF-16 strings, `DOMStrings` are mapped directly to strings. Passing `null` to a method that accepts a `DOMString` will convert `null` to `'null'` . The `createObbjectURL()` method accepts an object, which can be a `File`, `Blob`, or `MediaSource` object to create a URL for.For example, we can call the `createObjectURL()` method like in the following code:

```javascript
const objUrl = URL.createObjectURL(new File([""], "filename"));  
console.log(objUrl);
```

Then we get something like:

```
blob:https://fiddle.jshell.net/4cfe2ef3-74ea-4145-87a7-0483b117b429
```

Each time we create an object URL with the `createObjectURL()` method, we have to release it by calling the `revokeObjectURL()` method to clear it from memory. However, browser will release object URLs automatically when the document is unloaded, but for the sake for improving performance, we should release it manually. The `revokeObjectURL()` method takes in an object URL as its argument. For example, if we have the object URL above created, then we can use the `revokeObjectURL()` method to release the object URL from memory like in the following code:

```javascript
const objUrl = URL.createObjectURL(new File([""], "filename"));  
console.log(objUrl);  
URL.revokeObjectURL(objUrl);
```

The `revokeObjectURL()` method returns `undefined` .

When any part of the URL has special characters, they’re encoded by the rules found in RFC-3896, which has a long list of rules on how to encode different types of characters. It also includes non-English characters, and the percent encoding standard for encoding URLs. The full list of rules are at https://tools.ietf.org/html/rfc3986.

With the URL object, manipulating and extract parts from a URL is no longer a pain since we don’t have to write all the code to do it ourselves. Most browsers have the URL object built in to their standard library. Now we can pass in the URL as a string to the URL constructor and to create an instance of a URL. Then we can use the handy value properties and methods to manipulate and get the parts of a URL that we want. It can manipulate all parts of the URL except the query string portion, which can be manipulated by parsing it into a `URLSeachParams` object and then call its methods and set its properties to modify the query string. To `toString` and `toJSON` methods both convert a URL object into a full URL string.