URL: URL() constructor

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since ⁨April 2021⁩.

Note: This feature is available inWeb Workers.

TheURL() constructor returns a newly createdURL object representing the URL defined by the parameters.

If the given base URL or the resulting URL are not valid URLs, the JavaScriptTypeError exception is thrown.

A string or any other object with astringifier that represents an absolute URL or a relative reference to a base URL.Ifurl is a relative reference,base is required, and is used to resolve the final URL.Ifurl is an absolute URL, a givenbase will not be used to create the resulting URL.

baseOptional

A string representing the base URL to use in cases whereurl is a relative reference.If not specified, it defaults toundefined.

When abase is specified, the resolved URL is not simply a concatenation ofurl andbase.Relative references to the parent and current directory are resolved relative to the current directory of thebase URL, which includes path segments up until the last forward-slash, but not any after.Relative references to the root are resolved relative to the base origin.For more information seeResolving relative references to a URL.

Note:Theurl andbase arguments will each be stringified from whatever value you pass, such as anHTMLAnchorElement orHTMLAreaElement element, just like with other Web APIs that accept a string.In particular, you can use an existingURL object for either argument, and it will be stringified from the object'shref property.

Exceptions

TypeError: url (in the case of absolute URLs) orbase +url (in the case of relative references) is not a valid URL.

Examples

Here are some examples of using the constructor.

Note:Resolving relative references to a URL provides additional examples demonstrating how differenturl andbase values are resolved to a final absolute URL.

// Base URLs:let baseUrl = "https://developer.mozilla.org";let a = new URL("/", baseUrl);// => 'https://developer.mozilla.org/'let b = new URL(baseUrl);// => 'https://developer.mozilla.org/'new URL("en-US/docs", b);// => 'https://developer.mozilla.org/en-US/docs'let d = new URL("/en-US/docs", b);// => 'https://developer.mozilla.org/en-US/docs'new URL("/en-US/docs", d);// => 'https://developer.mozilla.org/en-US/docs'new URL("/en-US/docs", a);// => 'https://developer.mozilla.org/en-US/docs'new URL("/en-US/docs", "https://developer.mozilla.org/fr-FR/toto");// => 'https://developer.mozilla.org/en-US/docs'

Here are some examples of invalid URLs:

new URL("/en-US/docs", "");// Raises a TypeError exception as '' is not a valid URLnew URL("/en-US/docs");// Raises a TypeError exception as '/en-US/docs' is not a valid URL// Other cases:new URL("http://www.example.com");// => 'http://www.example.com/'new URL("http://www.example.com", B);// => 'http://www.example.com/'new URL("", "https://example.com/?query=1");// => 'https://example.com/?query=1' (Edge before 79 removes query arguments)new URL("/a", "https://example.com/?query=1");// => 'https://example.com/a' (see relative URLs)new URL("//foo.example", "https://example.com");// => 'https://foo.example/' (see relative URLs)