URL: URL() constructor
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 — including, for example, an
<a>
or<area>
element — that represents an absolute or relative URL. Ifurl
is a relative URL,base
is required, and will be used as the base URL. Ifurl
is an absolute URL, a givenbase
will be ignored. base
Optional-
A string representing the base URL to use in cases where
url
is a relative URL. If not specified, it defaults toundefined
.
Note: The url
and base
arguments will
each be stringified from whatever value you pass, 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 stringify to the
object's href
property.
The resulting URL is not simply a concatenation of url
and base
.
The path sections of both arguments are merged according to
RFC 3986 - Relative Resolution.
Therefore a trailing slash in base
or a leading slash in url
affect how the resulting path is constructed.
If you need a strict concatenation of the two arguments the url
must not have a leading slash
and the base
must have a trailing slash.
See the examples under Examples - Merging of url and base paths.
Exceptions
Exception | Explanation |
---|---|
TypeError |
url (in the case of absolute URLs) or base + url (in the case of relative URLs) is not a valid URL. |
Examples
// 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'
// 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.com", "https://example.com");
// => 'https://foo.com/' (see relative URLs)
Merging of url and base paths
/* base path without trailing slash */
const A = new URL("articles", "https://developer.mozilla.org/api/v1");
// => 'https://developer.mozilla.org/api/articles'
const B = new URL("/articles", "https://developer.mozilla.org/api/v1");
// => 'https://developer.mozilla.org/articles'
const C = new URL("./articles", "https://developer.mozilla.org/api/v1");
// => 'https://developer.mozilla.org/api/articles'
const D = new URL("../articles", "https://developer.mozilla.org/api/v1");
// => 'https://developer.mozilla.org/articles'
/* base path with trailing slash */
const E = new URL("articles", "https://developer.mozilla.org/api/v1/");
// => 'https://developer.mozilla.org/api/v1/articles'
const F = new URL("/articles", "https://developer.mozilla.org/api/v1/");
// => 'https://developer.mozilla.org/articles'
const G = new URL("./articles", "https://developer.mozilla.org/api/v1/");
// => 'https://developer.mozilla.org/api/v1/articles'
const H = new URL("../articles", "https://developer.mozilla.org/api/v1/");
// => 'https://developer.mozilla.org/api/articles'
Specifications
Specification |
---|
URL Standard # dom-url-url |
Browser compatibility
BCD tables only load in the browser
See also
- Polyfill of
URL
incore-js
- The interface it belongs to:
URL
.