How to build an URL and its search parameters with JavaScript

Learn how to build, validate, and parse an URL with the URL API: a clean interface for building and validating URLs with JavaScript.

Getting to know the URL API

A lot of developers use regular expressions to validate and build URLs in JavaScript, and for good reasons.

But whenever I need to build one, the URL API is my friend. Keep in mind, it is not supported in IE, but works well on modern browsers, as well as in Node.js.

It offers URL validation out of the box and a nice API for working with search parameters. To create an URL call the constructor like so:

const myUrl = new URL("https://www.valentinog.com");

Where’s the validation you might ask. No worries, you’ll be warned when the argument is invalid:

const myUrl = new URL("www.valentinog.com");
// TypeError: www.valentinog.com is not a valid URL.

What makes a valid URL for the URL API? An URL should have at least the host and the protocol, so the following example is formally valid, even if it lacks the extension:

const anotherUrl = new URL("https://w");

While the URL API is indeed handy, you might still need regular expressions for checking the extension. Anyway, there is support for the hash part too:

const anotherUrl = new URL("https://w.com/#about");
console.log(anotherUrl.hash);
// output: #about

But the URL API really shines for building search parameters. Jump to the next section for learning more!

How to build an URL and its search parameters

Suppose you want to build an URL like https://www.example.dev/?city=Rome&price=200. In this example the parts ?city=Rome&price=200 are search parameters, or query parameters, useful any time you need to send a query to the backend.

A naive approach for building the URL would involve JavaScript template literals:

const city = "Rome";
const price = "200";

const myNaiveUrl = `https://www.example.dev/?city=${city}&price=${price}`;

But this attack plan will quickly fall apart, leading to convoluted code. Luckily, the URL API has a property for interacting with search parameters. Look at this:

const myUrlWithParams = new URL("https://www.example.dev/");

myUrlWithParams.searchParams.append("city", "Rome");
myUrlWithParams.searchParams.append("price", "200");

console.log(myUrlWithParams.href);

// output: https://www.example.dev/?city=Rome&price=200

That’s how you build a proper URL.

Even if myUrlWithParams.searchParams is marked as read-only you can still change the original URL as you wish. Here searchParams is an URLSearchParams object which has an append method for adding new parameters to the search.

Conclusion

The URL API is a clean interface for building and validating URLs with JavaScript. It’s availabile in Node.js and in most modern browsers.

The URL API offers a first layer of validation for URLs, although it doesn’t enforce the TLD (top level domain). Still, it is a nice tool for building search parameters programmatically, and for parsing URLs in JavaScript.

Originally published on my blog.