Window: open() method
The open()
method of the Window
interface loads a specified resource into a new or existing browsing context (that is, a tab, a window, or an iframe) under a specified name.
Syntax
open()
open(url)
open(url, target)
open(url, target, windowFeatures)
Parameters
url
Optional-
A string indicating the URL or path of the resource to be loaded. If an empty string (
""
) is specified or this parameter is omitted, a blank page is opened into the targeted browsing context. target
Optional-
A string, without whitespace, specifying the name of the browsing context the resource is being loaded into. If the name doesn't identify an existing context, a new context is created and given the specified name. The special
target
keywords,_self
,_blank
(default),_parent
,_top
, and_unfencedTop
can also be used._unfencedTop
is only relevant to fenced frames.This name can be used as the
target
attribute of<a>
or<form>
elements. windowFeatures
Optional-
A string containing a comma-separated list of window features in the form
name=value
. Boolean values can be set to true using one of:name
,name=yes
,name=true
, orname=n
wheren
is any non-zero integer. These features include options such as the window's default size and position, whether or not to open a minimal popup window, and so forth. The following options are supported:attributionsrc
Experimental-
Indicates that you want the browser to send an
Attribution-Reporting-Eligible
header along with theopen()
call. This call must be made with transient activation (i.e. inside a user interaction event handle such asclick
), within five seconds of user interaction. On the server-side this is used to trigger sending anAttribution-Reporting-Register-Source
header in the response to complete registration of an attribution source.In addition, the browser is also triggered to store the associated source data (as provided in the
Attribution-Reporting-Register-Source
response header) when theopen()
method completes.See the Attribution Reporting API for more details.
Note:
open()
calls cannot be used to register an attribution trigger. popup
-
By default,
window.open
opens the page in a new tab. Ifpopup
is set to true, it requests that a minimal popup window be used. The UI features included in the popup window will be automatically decided by the browser, generally including an address bar only. Ifpopup
is present and set to false, a new tab is still opened.There are a few legacy features, which used to control UI features of the opened window. In modern browsers, they only have the effect of requesting a popup. If
popup
is unspecified, andwindowFeatures
contains any features (including unrecognized ones) other thannoopener
,noreferrer
, orattributionsrc
, the window is also opened as a popup if any of the following conditions apply:location
andtoolbar
are both false or absentmenubar
is false or absentresizable
is falsescrollbars
is false or absentstatus
is false or absent
Otherwise the window is opened as a tab.
width
orinnerWidth
-
Specifies the width of the content area, including scrollbars. The minimum required value is 100.
height
orinnerHeight
-
Specifies the height of the content area, including scrollbars. The minimum required value is 100.
left
orscreenX
-
Specifies the distance in pixels from the left side of the work area as defined by the user's operating system where the new window will be generated.
top
orscreenY
-
Specifies the distance in pixels from the top side of the work area as defined by the user's operating system where the new window will be generated.
noopener
-
If this feature is set, the new window will not have access to the originating window via
Window.opener
and returnsnull
.When
noopener
is used, non-empty target names, other than_top
,_self
, and_parent
, are treated like_blank
in terms of deciding whether to open a new browsing context. noreferrer
-
If this feature is set, the browser will omit the
Referer
header, as well as setnoopener
to true. Seerel="noreferrer"
for more information.
A
null
value is treated the same as the empty string (""
).
Note: Requested position (top
, left
), and requested dimension (width
, height
) values in windowFeatures
will be corrected if any of such requested value does not allow the entire browser popup to be rendered within the work area for applications of the user's operating system. In other words, no part of the new popup can be initially positioned offscreen.
Return value
If the browser successfully opens the new browsing context, a WindowProxy
object is returned.
The returned reference can be used to access properties and methods of the new context as long as it complies with the same-origin policy security requirements.
If the Cross-Origin-Opener-Policy
HTTP header is being used, and the document policies are such that the document is opened in a new browsing context group, references to the opened window are severed and the returned object will indicate that the opened window is closed (closed
is true
).
null
is returned if the browser fails to open the new browsing context, for example because it was blocked by a browser popup blocker.
Description
The Window
interface's open()
method takes a URL as a parameter, and loads the resource it identifies into a new or existing tab or window. The target
parameter determines which window or tab to load the resource into, and the windowFeatures
parameter can be used to control to open a new popup with minimal UI features and control its size and position.
Remote URLs won't load immediately. When window.open()
returns, the window always contains about:blank
. The actual fetching of the URL is deferred and starts after the current script block finishes executing. The window creation and the loading of the referenced resource are done asynchronously.
Modern browsers have strict popup blocker policies. Popup windows must be opened in direct response to user input, and a separate user gesture event is required for each Window.open()
call. This prevents sites from spamming users with lots of windows. However, this poses an issue for multi-window applications. To work around this limitation, you can design your applications to:
- Open no more than one new window at once.
- Reuse existing windows to display different pages.
- Advise users on how to update their browser settings to allow multiple windows.
Examples
Opening a new tab
window.open("https://www.mozilla.org/", "mozillaTab");
Opening a popup
Alternatively, the following example demonstrates how to open a popup, using the popup
feature.
window.open("https://www.mozilla.org/", "mozillaWindow", "popup");
It is possible to control the size and position of the new popup:
const windowFeatures = "left=100,top=100,width=320,height=320";
const handle = window.open(
"https://www.mozilla.org/",
"mozillaWindow",
windowFeatures,
);
if (!handle) {
// The window wasn't allowed to open
// This is likely caused by built-in popup blockers.
// …
}
Progressive enhancement
In some cases, JavaScript is disabled or unavailable and window.open()
will not work. Instead of solely relying on the presence of this feature, we can provide an alternative solution so that the site or application still functions.
Provide alternative ways when JavaScript is disabled
If JavaScript support is disabled or non-existent, then the user agent will create a secondary window accordingly or will render the referenced resource according to its handling of the target
attribute. The goal and the idea are to provide (and not impose) to the user a way to open the referenced resource.
HTML
<a href="https://www.wikipedia.org/" target="OpenWikipediaWindow">
Wikipedia, a free encyclopedia (opens in another, possibly already existing,
tab)
</a>
JavaScript
let windowObjectReference = null; // global variable
function openRequestedTab(url, windowName) {
if (windowObjectReference === null || windowObjectReference.closed) {
windowObjectReference = window.open(url, windowName);
} else {
windowObjectReference.focus();
}
}
const link = document.querySelector("a[target='OpenWikipediaWindow']");
link.addEventListener(
"click",
(event) => {
openRequestedTab(link.href);
event.preventDefault();
},
false,
);
The above code solves a few usability problems related to links opening popups. The purpose of the event.preventDefault()
in the code is to cancel the default action of the link: if the event listener for click
is executed, then there is no need to execute the default action of the link. But if JavaScript support is disabled or non-existent on the user's browser, then the event listener for click
is ignored, and the browser loads the referenced resource in the target frame or window that has the name "WikipediaWindowName"
. If no frame nor window has the name "WikipediaWindowName"
, then the browser will create a new window and name it "WikipediaWindowName"
.
Reuse existing windows and avoid target="_blank"
Using "_blank"
as the target attribute value will create several new and unnamed windows on the user's desktop that cannot be recycled or reused. Try to provide a meaningful name to your target
attribute and reuse such target
attribute on your page so that a click on another link may load the referenced resource in an already created and rendered window (therefore speeding up the process for the user) and therefore justifying the reason (and user system resources, time spent) for creating a secondary window in the first place. Using a single target
attribute value and reusing it in links is much more user resources friendly as it only creates one single secondary window, which is recycled.
Here is an example where a secondary window can be opened and reused for other links:
HTML
<p>
<a href="https://www.wikipedia.org/" target="SingleSecondaryWindowName">
Wikipedia, a free encyclopedia (opens in another, possibly already existing,
tab)
</a>
</p>
<p>
<a
href="https://support.mozilla.org/products/firefox"
target="SingleSecondaryWindowName">
Firefox FAQ (opens in another, possibly already existing, tab)
</a>
</p>
JavaScript
let windowObjectReference = null; // global variable
let previousURL; /* global variable that will store the
url currently in the secondary window */
function openRequestedSingleTab(url) {
if (windowObjectReference === null || windowObjectReference.closed) {
windowObjectReference = window.open(url, "SingleSecondaryWindowName");
} else if (previousURL !== url) {
windowObjectReference = window.open(url, "SingleSecondaryWindowName");
/* if the resource to load is different,
then we load it in the already opened secondary window and then
we bring such window back on top/in front of its parent window. */
windowObjectReference.focus();
} else {
windowObjectReference.focus();
}
previousURL = url;
/* explanation: we store the current url in order to compare url
in the event of another call of this function. */
}
const links = document.querySelectorAll(
"a[target='SingleSecondaryWindowName']",
);
for (const link of links) {
link.addEventListener(
"click",
(event) => {
openRequestedSingleTab(link.href);
event.preventDefault();
},
false,
);
}
Same-origin policy
If the newly opened browsing context does not share the same origin, the opening script will not be able to interact (reading or writing) with the browsing context's content.
// Script from example.com
const otherOriginContext = window.open("https://example.org");
// example.com and example.org are not the same origin
console.log(otherOriginContext.origin);
// DOMException: Permission denied to access property "origin" on cross-origin object
// Script from example.com
const sameOriginContext = window.open("https://example.com");
// This time, the new browsing context has the same origin
console.log(sameOriginContext.origin);
// https://example.com
For more information, refer to the Same-origin policy article.
Accessibility concerns
Avoid resorting to window.open()
It is preferable to avoid resorting to window.open()
, for several reasons:
- Modern browsers offer a popup-blocking feature.
- Modern browsers offer tab-browsing, and tab-capable browser users prefer opening new tabs to opening new windows in most situations.
- Users may use browser built-in features or extensions to choose whether to open a link in a new window, in the same window, in a new tab, the same tab, or in the background. Forcing the opening to happen in a specific way, using
window.open()
, will confuse them and disregard their habits. - Popups don't have a menu toolbar, whereas new tabs use the user interface of the browser window; therefore, many users prefer tab-browsing because the interface remains stable.
Never use window.open() inline in HTML
Avoid <a href="#" onclick="window.open(…);">
or <a href="javascript:window\.open(…)" …>
.
These bogus href
values cause unexpected behavior when copying/dragging links, opening links in a new tab/window, bookmarking, or when JavaScript is loading, errors, or is disabled. They also convey incorrect semantics to assistive technologies, like screen readers.
If necessary, use a <button>
element instead. In general, you should only use a link for navigation to a real URL.
Always identify links leading to a secondary window
Identify links that will open new windows in a way that helps navigation for users.
<a target="WikipediaWindow" href="https://www.wikipedia.org">
Wikipedia (opens in new tab)
</a>
The purpose is to warn users of context changes to minimize confusion on the user's part: changing the current window or popping up new windows can be very disorienting to users (in the case of a popup, no toolbar provides a "Previous" button to get back to the previous window).
When extreme changes in context are explicitly identified before they occur, then the users can determine if they wish to proceed or so they can be prepared for the change: not only they will not be confused or feel disoriented, but more experienced users can better decide how to open such links (in a new window or not, in the same window, in a new tab or not, in "background" or not).
Specifications
Specification |
---|
HTML Standard # dom-open-dev |
CSSOM View Module # the-features-argument-to-the-open()-method |
Browser compatibility
BCD tables only load in the browser
See also
target
attribute documentation:window.close()
window.closed
window.focus()
window.opener
rel="opener"
andrel="noopener"
- Same-origin policy