Complete cross-browser window.open() documentation

Syntax

WindowObjectReference = window.open(strUrl, strWindowName [, strWindowFeatures]);

Return value and parameters

WindowObjectReference

This is the reference pointing to the newly created browser window. This reference is the return value of the open() method; such reference will exist only if the window.open() instruction succeeded. A global variable is best used to store such reference. This window reference can be useful and is needed to access properties and methods of the new browser window.

strUrl

This is the URL to be loaded in the newly opened window. strUrl can be an HTML document on the web, it can be an image file or any type of file supported by the browser.

strWindowName

This is the string that just names the new window. Such string can be used to be the target of links and forms when the target attribute of an <a> element or of a <form> is specified. This string parameter should not contain any blank space. strWindowName does not specify the title of the new window.

strWindowFeatures

Optional parameter. This parameter is the string which lists the requested window features (window functionalities and toolbars) of the new browser window. This string parameter must not contain any blank space. Each requested window feature must be separated by a comma inside the character string.

[Page Content]

Description

The open method creates a new secondary browser window, similar to choosing New Window from the File menu. The strUrl parameter specifies the URL to be fetched and loaded in the new window. If strUrl is an empty string, then a new blank, empty window is created with all the default toolbars of the main window.

Best recommendable practices

<script type="text/javascript">
var WindowObjectReference; // global variable
function openFFPromotionPopup()
{
if(WindowObjectReference == null || WindowObjectReference.closed)
/* explanation: if the pointer to the window object
in memory does not exist or
if such pointer exists but the window was closed */
  {
  WindowObjectReference = window.open("http://www.spreadfirefox.com/",
  "PromoteFirefoxWindowName", "resizable=yes,scrollbars=yes,status=yes");
  }
/* explanation: then create it. The new window will be created and
will be brought on top of any other window. */
else
  {
  if(WindowObjectReference.focus)
    {
    WindowObjectReference.focus();
    };
  };

/* explanation: else the window reference must exist and the window
is not closed; therefore, we can bring it back on top of any other
window (and giving it system focus) with the focus() function. There
would be no need to re-create the window or to reload the referenced
resource.

But first, we need to test, to verify the support of the focus()
function before calling it.*/
}
</script>

(...)

<p><a href="http://www.spreadfirefox.com/" target="PromoteFirefoxWindowName"
onclick="openFFPromotionPopup(); return false;">Promote
Firefox adoption</a></p>
      

The above code solves a few usability problems related to links opening secondary window. The purpose of the return false in the code is to cancel default action of the link: if the onclick event handler 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 onclick event handler is ignored and the browser loads the referenced resource in the target frame or window that has the name "PromoteFirefoxWindowName". If no frame nor window has the name "PromoteFirefoxWindowName", then the browser will create a new window and will name it "PromoteFirefoxWindowName".
More reading on the use of the target attribute:
HTML 4.01 Target attribute specification
How to create a link that opens a new window?

You can also parameterize the function to make it versatile, functional in more situations, therefore re-usable in scripts and webpages:

<script type="text/javascript">
var WindowObjectReference; // global variable
function openRequestedPopup(strUrl, strWindowName)
{
if(WindowObjectReference == null || WindowObjectReference.closed)
  {
  WindowObjectReference = window.open(strUrl, strWindowName,
  "resizable=yes,scrollbars=yes,status=yes");
  }
else
  {
  if(WindowObjectReference.focus)
    {
    WindowObjectReference.focus();
    };
  };
}
</script>

(...)

<p><a href="http://www.spreadfirefox.com/" target="PromoteFirefoxWindow"

onclick="openRequestedPopup(this.href, this.target); return false;">Promote
Firefox adoption</a></p>
      

You can also make such function able to open only 1 secondary window and to reuse such single secondary window for other links in this manner:

<script type="text/javascript">
var WindowObjectReference; // global variable
var PreviousUrl; /* global variable which will store
the url currently in the secondary window */
function openRequestedSinglePopup(strUrl)
{
if(WindowObjectReference == null || WindowObjectReference.closed)
  {
  WindowObjectReference = window.open(strUrl, "SingleSecondaryWindowName",
  "resizable=yes,scrollbars=yes,status=yes");
  }
else if(previousUrl != strUrl)
  {
  WindowObjectReference = window.open(strUrl, "SingleSecondaryWindowName",
  "resizable=yes,scrollbars=yes,status=yes");
  if(WindowObjectReference.focus)
    {
    WindowObjectReference.focus();
    };
  /* explanation: 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.

  We verify first the support of the focus() function before
  calling it. */
  }
else
  {
  if(WindowObjectReference.focus)
    {
    WindowObjectReference.focus();
    };
  };
PreviousUrl = strUrl;
/* explanation: we store the current url in order to compare url
in the event of another call of this function. */
}
</script>

(...)

<p><a href="http://www.spreadfirefox.com/" target="SingleSecondaryWindowName"
onclick="openRequestedSinglePopup(this.href); return false;">Promote
Firefox adoption</a></p>

<p><a href="http://www.mozilla.org/support/firefox/faq"
target="SingleSecondaryWindowName"
onclick="openRequestedSinglePopup(this.href); return false;">Firefox FAQ</a></p>
      

[Page Content]

FAQ

1. How to prevent the message box asking the user if he wants to close the window?

   You can not. New windows not opened by javascript can not as a rule be closed by javascript. The javascript console in Mozilla-based browsers will report the warning message:
   "Scripts may not close windows that were not opened by script."
   Otherwise the history of URLs visited during the browser session would be lost.
   More on the window.close() method

2. How to bring back the window if minimized or if the window is behind another window?

   First check for the existence of the window object reference of such window and if it exists and if it has not been closed, then use focus() method. There is no other reliable and efficient way. You can examine an example explaining how to use the focus() method.

3. How do I force a maximized window?

   You can not. All browser manufacturers try to make the opening of new secondary windows noticed by users and noticeable by users to avoid confusion, to avoid disorienting users.

4. How do I turn off window resizability or remove toolbars?

   You can not by force. Mozilla-based users can have absolute control over window functionalities (resizability and scrollability) and toolbars presence by editing user preferences in about:config or via advanced prefs. Since your users are the ones who are targeted to view and to use such windows (not you, the web author), then best is to avoid interfering with their habits and preferences. We recommend to always set the resizability and scrollbars presence (if needed) to yes to insure accessibility to content and usability of windows. This is in the best interests of the web author and of the users.

   Starting with Firefox 3, all windows are resizable and have the location bar.

5. How to resize a window to fit its content?

   You can not reliably because the users can prevent the window from being resized by unchecking the
   Edit/Preferences/Advanced/Scripts & Plug-ins/Allow Scripts to/
   Move or resize existing windows checkbox in Mozilla or
   Tools/Options/Web Features/Enable Javascript/Advanced button/
   Move or resize existing windows checkbox in Firefox or by setting
   dom.disable_window_move_resize
   to true in the about:config or by editing accordingly their user.js file. In general, users usually disable moving and resizing of existing windows because allowing authors' scripts to do so has been abused overwhelmingly in the past and the rare scripts that do not abuse such feature are often wrong, inaccurate when resizing the window. 99% of all those scripts disable window resizability and disable scrollbars when in fact they should enable both of these features to allow a cautious and sane fallback mechanism if their calculations are wrong. The window method sizeToContent() is also disabled if the user uncheck the preference Move or resize existing windows checkbox. Moving and resizing a window remotedly on the user's screen via script will very often annoy the users, will disorient the user and will be wrong at best. The web author expects he can have full control of (and can decide about) every position and size aspects of the users' browser window ... which is simply not true.

6. How do I open a referenced resource of a link into a new tab? or in a specific tab?

   Currently, you can not. Only the user can set his advanced preferences to do that. K-meleon 1.5, a Mozilla-based browser, gives complete control and power to the user regarding how links are opened. Some advanced extensions also give Mozilla and Firefox a lot of power over how referenced resources are loaded.
   In a few years from now, the target property of the CSS3 hyperlink module may be implemented (if CSS3 Hyperlink module as it is right now is approved). And even if and when such possibility happens, you can expect browser manufacturers and Mozilla browsers (and other browsers based on/offering tab-browsing) to give the user entire veto power and full control over how links can open web pages. How to open a link should always be entirely under the control and the power of the user.

7. How do I know if a window has opened, is still opened?

   You can test for the existence of the window object reference which is the returned value in case of success of the window.open() call and then verify that WindowObjectReference.closed return value is false but this is not a reliable way to detect presence of an active popup blocking software.
   Microsoft answers pretty much the same: How can I tell if Internet Explorer has blocked my pop-up window? Functions that return a window object will return null if the window is blocked. Always check the return value of window.open() before using it to avoid script errors when pop-ups are blocked. quote from Finetune Your Web Site for XP SP2

8. What is the javascript relationship between the main window and the secondary window?

   The return value of the window.open() method and the opener keyword. The WindowObjectReference links the main (opener) window to the secondary (sub-window) window while the opener keyword will link the secondary window to its main (opener) window.

9. I can not access the properties of the new secondary window. I always get an error in the javascript console saying "Error: uncaught exception: Permission denied to get property <property_name or method_name>". Why is that?

   It is because of the cross-domain script security restriction (also referred as the "Same Origin Policy"). A script loaded in a window (or frame) from a distinct origin (domain name) cannot get nor set properties of another window (or frame) or the properties of any of its HTML objects coming from another distinct origin (domain name). Therefore, before executing a script targeting a secondary window, the browser in the main window will verify that the secondary window has the same domain name.
   More reading on the cross-domain script security restriction:
   https://developer.mozilla.org/En/Same_origin_policy_for_JavaScript

[Page Content]

Usability issues

Generally speaking, it is preferable to avoid resorting to window.open() for several reasons:

• all Mozilla-based browsers offer tab-browsing and this is the preferred mode of opening referenced resources... not just in Mozilla-based browsers but in all other browsers offering tab-browsing. In other words, tab-capable browser users overall prefer opening new tabs than opening new windows in a majority of webpage situations. Tab-capable browsers have rapidly gained support and enthusiasm on internet in the last 3 years; this trend will not revert back. MSIE 7, released in October 2006, has full support for tab browsing.
• there are now several Mozilla extensions (like Multizilla) and Firefox extensions (like Tabbrowser preferences), features, settings and advanced preferences based on tab-browsing and based on converting window.open() calls into opening tabs, based on neutralizing window.open() calls, in particular in neutralizing unrequested openings of new windows (often referred as blocking unrequested popups or as blocking script-initiated windows opening automatically). Coding carelessly to open new windows can no longer be assured of success, can not succeed by force and, if it does, can annoy a majority of users.
• new windows can have menubar missing, scrollbars missing, status bar missing, window resizability disabled, etc.; new tabs can not be missing those functionalities or toolbars (or at least, the toolbars which are present by default). Therefore, tab-browsing is preferred by a lot of users because the normal user-interface of the browser window they prefer is kept intact, remains stable.
• opening new windows, even with reduced features, uses considerably a lot of the user's system resources (CPU, RAM) and involves considerably a lot of coding in the source code (security management, memory management, various code branchings sometimes quite complex, window frame/chrome/toolbars building, window positioning and sizing, etc.). Opening new tabs is less demanding on the user's system resources (and faster to achieve) than opening new windows.

If you want to offer to open a link in a new window, then follow tested and recommendable usability and accessibility guidelines:

• Never use "javascript:" in your links; never use this form of code:
  <a href="javascript:window.open(...)" ...>.
  "javascript:" links break accessibility and usability of webpages for all browsers and in multiple manners:
  • "javascript:" pseudo-links become dysfunctional when javascript support is disabled or inexistent. Several corporations allow their employees to surf on the web but under strict security policies: no javascript enabled, no java, no activeX, no Flash. For various reasons (security, public access, text browsers, etc..), about 8% to 12% of users on the web surf with javascript disabled.
  • "javascript:" links are known to interfere with advanced features in tab-capable browsers: eg. middle-click on links, Ctrl+click on links
  • "javascript:" links will interfere with the process of indexing webpages by search engines.
  • "javascript:" links interfere with assistive technologies and several web-aware applications (e.g. PDA).
  • "javascript:" links also interfere with "mouse gestures" features implemented in browsers.
  • Protocol scheme "javascript:" will be reported as an error by link validators and link checkers.
  Top Ten Web-Design Mistakes of 2002, 6. JavaScript in Links, Jakob Nielsen, December 2002
  Links & JavaScript Living Together in Harmony, Jeff Howden, February 2002
  comp.lang.javascript newsgroup discussion FAQ on "javascript:" links
• Never use <a href="#" onclick="window.open(...);". Such pseudo-link also breaks accessibility of links. Always use a real URL for the href attribute value so that if javascript support is disabled or inexistent or if the user agent does not support opening of secondary window (like MS-Web TV, text browsers, etc), then such user agents will still be able to load the referenced resource accordingly. This form of code also interferes with advanced features in tab-capable browsers: eg. middle-click on links, Ctrl+click on links.

• Always identify links which will create (or will re-use) a new, secondary window in a way that helps navigation for users:
  by coding the title attribute of the link, by adding an icon at the end of the link or by coding the cursor accordingly.

  "if your link spawns a new window, or causes another windows to 'pop up' on your display, or move the focus of the system to a new FRAME or Window, then the nice thing to do is to tell the user that something like that will happen."
  quote from World Wide Web Consortium Accessibility Initiative regarding popups

  "Use link titles to provide users with a preview of where each link will take them, before they have clicked on it."
  quote from Ten Good Deeds in Web Design, Jakob Nielsen, October 1999

  Using Link Titles to Help Users Predict Where They Are Going, Jakob Nielsen, January 1998

  Examples of "new windows" icons used on the web:

  Examples of cursors used on the web:
  cursor from http://www.draig.de/LinkBar/#features
  cursor from http://mithgol.ru/Mozilla/
  The purpose is to warn users in advance 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 (Back toolbar button is disabled).

  "Users often don't notice that a new window has opened, especially if they are using a small monitor where the windows are maximized to fill up the screen. So a user who tries to return to the origin will be confused by a grayed out Back button."
  quote from The Top Ten New Mistakes of Web Design: 2. Opening New Browser Windows, Jakob Nielsen, May 1999

  When extreme changes in context are explicitly identified before they occur, then the users can determine if they wish to proceed otherwise 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).

• Always use the target attribute. 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: e.g. some user agents which can not create new windows, like MS Web TV, will fetch the referenced resource and append it at the end of the current document. The goal and the idea is to try to provide - not impose - to the user a way to open the referenced resource, a mode of opening the link. Your code should not interfere with the features of the browser at the disposal of the user and your code should not interfere with the final decision resting with the user.
• Do not use target="_blank" to force links to open in a new window; instead, always provide a meaningful name to your target attribute and try to reuse such target attribute in 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. In any case, if your code is well done, it will not interfere with the user's final choice but will rather merely offer him more choices, more ways to open links and more power to the tool he's using (a browser).

Glossary

Opener window, parent window, main window, first window

terms often used to describe or to identify the same window. It is the window from which a new window will be created. It is the window on which the user clicked a link which lead to the creation of another, new window.

Sub-window, child window, secondary window, second window

terms often used to describe or to identify the same window. It is the new window which was created.

Unrequested popup windows

script-initiated windows opening automatically without the user's consent.

Specification

DOM Level 0. window.open() is not part of any W3C specification or technical recommendation.

[Page Content]

Notes

Note on precedence

In cases where left and screenX (and/or top and screenY) have conflicting values, then left and top have precedence over screenX and screenY respectively. If left and screenX (and/or top and screenY) are defined in the strWindowFeatures list, then left (and/or top) will be honored and rendered. E.g.:

WindowObjectReference = window.open("http://news.bbc.co.uk/", "BBCWorldNewsWindowName",
"left=100,screenX=200,resizable,scrollbars,status");
Result: here, the new window will be positioned at 100 pixels from the
left side of the work area for applications of the user's operating
system, not at 200 pixels.
      

If left is set but top has no value and screenY has a value, then left and screenY will be the coordinate positioning values of the secondary window.

outerWidth has precedence over width and width has precedence over innerWidth.
outerHeight has precedence over height and height has precedence over innerHeight.

WindowObjectReference = window.open("http://www.wwf.org/",
"WWildlifeOrgWindowName",
"outerWidth=600,width=500,innerWidth=400,resizable,scrollbars,status");

Result: here, Mozilla-browsers will create a new window with an outerWidth
of 600 pixels wide and will ignore the request of a width of 500 pixels
and will also ignore the request of an innerWidth of 400 pixels.
      

Note on position and dimension error correction

Requested position and requested dimension values in the strWindowFeatures list will not be honored and will be corrected if any of such requested value does not allow the entire browser window to be rendered within the work area for applications of the user's operating system. No part of the new window can be initially positioned offscreen. This is by default in all Mozilla-based browser releases.
MSIE 6 has a similar error correction mechanism but it is not activated by default in all security levels: a security setting can disable such error correction mechanism.

Note on scrollbars

When content overflows window viewport dimensions, then scrollbar(s) (or some scrolling mechanism) are necessary to insure that content can be accessed by users. Content can overflow window dimensions for several reasons which are outside the control of web authors:

• user resizes the window
• user increases the text size of fonts via View/Text Zoom (%) menuitem in Mozilla or View/Text Size/Increase or Decrease in Firefox
• user sets a minimum font size for pages which is bigger than the font-size the web author requested. People over 40 years old or with particular viewing habit or reading preference often set a minimal font size in Mozilla-based browsers.
• web author is not aware of default margin (and/or border and/or padding) values applying to root element or body node in various browsers and various browser versions
• user uses an user stylesheet (userContent.css in Mozilla-based browsers) for his viewing habits which increases document box dimensions (margin, padding, default font size)
• user can customize individually the size (height or width) of most toolbars via operating system settings. E.g. window resizing borders, height of browser titlebar, menubar, scrollbars, font size are entirely customizable by the user in Windows XP operating system. These toolbars dimensions can also be set via browser themes and skins or by operating system themes
• web author is unaware that the user default browser window has custom toolbar(s) for specific purpose(s); e.g.: prefs bar, web developer bar, accessibility toolbar, popup blocking and search toolbar, multi-feature toolbar, etc.
• user uses assistive technologies or add-on features which modify the operating system's work area for applications: e.g. MS-Magnifier
• user repositions and/or resizes directly or indirectly the operating system's work area for applications: e.g. user resizes the Windows taskbar, user positions the Windows taskbar on the left side (arabic language based) or right side (Hebrew language), user has a permanent MS-Office quick launch toolbar, etc.
• some operating system (Mac OSX) forces presence of toolbars which can then fool the web author's anticipations, calculations of the effective dimensions of the browser window

Note on status bar

You should assume that a large majority of users' browsers will have the status bar or that a large majority of users will want to force the status bar presence: best is to always set this feature to yes. Also, if you specifically request to remove the status bar, then Firefox users will not be able to view the Site Navigation toolbar if it is installed. In Mozilla and in Firefox, all windows with a status bar have a window resizing grippy at its right-most side. The status bar also provides info on http connection, hypertext resource location, download progress bar, encryption/secure connection info with SSL connection (displaying a yellow padlock icon), internet zone icons, privacy policy/cookie icon, etc. Removing the status bar usually removes a lot of functionalities, features and info which are considered useful and sometimes vital by the users and for the users.

Note on security issues of the status bar presence

in MSIE 6 for XP SP2:

"For windows opened using window.open():
Expect the status bar to be present, and code for it. The status bar will be on by default and is 20-25 pixels in height. (...)"
quote from Fine-Tune Your Web Site for Windows XP Service Pack 2, Browser Window Restrictions in XP SP2

"(...) windows that are created using the window.open() method can be called by scripts and used to spoof a user interface or desktop or to hide malicious information or activity by sizing the window so that the status bar is not visible.
Internet Explorer windows provide visible security information to the user to help them ascertain the source of the Web page and the security of the communication with that page. When these elements are not in view, the user might think they are on a more trusted page or interacting with a system process when they are actually interacting with a malicious host. (...)
Script-initiated windows will be displayed fully, with the Internet Explorer title bar and status bar. (...)
Script management of Internet Explorer status bar
Detailed description
Internet Explorer has been modified to not turn off the status bar for any windows. The status bar is always visible for all Internet Explorer windows. (...) Without this change, windows that are created using the window.open() method can be called by scripts and spoof a user interface or desktop or hide malicious information or activity by hiding important elements of the user interface from the user.
The status bar is a security feature of Internet Explorer windows that provides Internet Explorer security zone information to the user. This zone cannot be spoofed (...)"
quote from Changes to Functionality in Microsoft Windows XP Service Pack 2, Internet Explorer Window Restrictions

Note on fullscreen

In MSIE 6 for XP SP2:

"window.open() with fullscreen=yes will now result in a maximized window, not a kiosk mode window."
quote from From Fine-Tune Your Web Site for Windows XP Service Pack 2.

"the definition of the fullscreen=yes specification is changed to mean 'show the window as maximized,' which will keep the title bar, address bar, and status bar visible. (...)"
quote from Changes to Functionality in Microsoft Windows XP Service Pack 2, Script sizing of Internet Explorer windows

[Page Content]

Note on outerHeight and height

Tutorials

Javascript windows (tutorial) by Lasse Reichstein Nielsen

The perfect pop-up (tutorial) by accessify.com

Popup windows and Firefox: interactive demos by Gérard Talbot

References

Links Want To Be Links by Jukka K. Korpela

Links & JavaScript Living Together in Harmony by Jeff Howden

window.open() reference at developer.mozilla.org