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 in Web Workers.
The URL() constructor returns a newly created URL object representing the URL defined by the parameters.
If the given base URL or the resulting URL are not valid URLs, the JavaScript TypeError exception is thrown.
Syntax
new URL(url)
new URL(url, base)
Parameters
url-
A string or any other object with a stringifier that represents an absolute URL or a relative reference to a base URL. If
urlis a relative reference,baseis required, and is used to resolve the final URL. Ifurlis an absolute URL, a givenbasewill not be used to create the resulting URL. baseOptional-
A string representing the base URL to use in cases where
urlis a relative reference. If not specified, it defaults toundefined.When a
baseis specified, the resolved URL is not simply a concatenation ofurlandbase. Relative references to the parent and current directory are resolved relative to the current directory of thebaseURL, 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 see Resolving relative references to a URL.
Note:
The url and base arguments will each be stringified from whatever value you pass, such as an HTMLAnchorElement or HTMLAreaElement element, just like with other Web APIs that accept a string.
In particular, you can use an existing URL object for either argument, and it will be stringified from the object's href 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 different url and base 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 URL
new 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)
Specifications
| Specification |
|---|
| URL # dom-url-url |
Browser compatibility
| desktop | mobile | server | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
URL() constructor
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Legend
Tip: you can click/tap on a cell for more information.
- Full support
- Full support
- Partial support
- Partial support
- See implementation notes.
- Has more compatibility info.
See also
URL.parse(), a non-throwing alternative to this constructor- Polyfill of
URLincore-js - The interface it belongs to:
URL.