dom / latest / url / url.html /

URL()

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.

Note: This feature is available in Web Workers

Syntax

new URL(url)
new URL(url, base)

Parameters

url

A USVString or any other object with a stringifier — including, for example, an <a> or <area> element — that represents an absolute or relative URL. If url is a relative URL, base is required, and will be used as the base URL. If url is an absolute URL, a given base will be ignored.

base Optional

A USVString representing the base URL to use in cases where url is a relative URL. If not specified, it defaults to undefined.

Note: The url and base arguments will each be stringified from whatever value you pass, just like with other Web APIs that accept USVString. In particular, you can use an existing URL object for either argument, and it will stringify to the object's href property.

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 m = 'https://developer.mozilla.org';
let a = new URL("/", m);                                // => 'https://developer.mozilla.org/'
let b = new URL(m);                                     // => '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'

        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
        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)

Specifications

Specification
URL Standard
# constructors

Browser compatibility

Desktop Mobile
Chrome Edge Firefox Internet Explorer Opera Safari WebView Android Chrome Android Firefox for Android Opera Android Safari on IOS Samsung Internet
URL
19
12
Before Edge 79, query arguments in the base URL argument are removed when calling the URL constructor.
26
No
15
14.1
6
In Safari 14 and earlier, calling the URL constructor with a base URL whose value is undefined causes Safari to throw a TypeError; see WebKit bug 216841.
4.4
25
26
14
14.5
6
In Safari 14 and earlier, calling the URL constructor with a base URL whose value is undefined causes Safari to throw a TypeError; see WebKit bug 216841.
1.5

See also

© 2005–2021 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/URL/URL

Name Web APIs
Version
Badge
Last Updated 2022-04-27T09:33:08Z