[Chapter 21] Reference: Window.open()
Author: David Flanagan
Date: Fri Aug 29 11:21:24 1997

#

| Chapter 21 JavaScript Reference |

# Window.open() Method

## Name

Window.open() Method---open a new browser window or locate a named window

## Availability

Navigator 2.0, Internet Explorer 3.0; enhanced in Navigator 3.0

## Synopsis

    window.open(url, name, [features, [replace]])

### Arguments

`url`

  A string that specifies the URL to be displayed in the new window, or the empty string for a blank window. This argument is optional in Navigator 2.0 and 3.0, but is required in Internet Explorer 3.0.

`name`

  A string of alphanumeric and underscore characters that specifies a name for the new window. This name can be used as the value of the `TARGET` attribute of `<A>` and `<FORM>` HTML tags. If this argument names a window that already exists, then the `open()` method will not create a new window, but will simply return a reference to the named window. In this case, the `features` argument is ignored. This argument is optional in Navigator 2.0 and 3.0, but is required in Internet Explorer 3.0.

`features`

  A string that specifies which features of a standard browser window are to appear in the new window. The format of this string is specified below. This argument is optional; if it is not specified, then the new window will have all standard features.

`replace`

  An optional Boolean argument that specifies whether the `url` that is loaded into the new page should create a new entry in the window's browsing history or replace the current entry in the browsing history. If this argument is `true` then no new history entry will be created. This argument is not supported by Navigator 2.0 or Internet Explorer 3.0, although those browsers will ignore it if it is specified. Also, notice that it doesn't make much sense to use this argument for newly created windows; it is intended for use when changing the contents of an existing window.

### Returns

A reference to a Window object, which may be newly created, or to an already existing one.

## Description

The `open()` method looks up an already existing window or opens a new browser window. If the `name` argument specifies the name of an existing window, then a reference to that window is returned. The returned window will display the URL specified by `url`, but the `features` argument will be ignored. This is the only way in JavaScript to obtain a reference to a window which is known only by name.

If the `name` argument is not specified, or if no window with that name already exists, the the `open()` method creates a new browser window. The created window displays the URL specified by `url`, has the name specified by `name`, and has the size and controls specified by `features` (the format of this argument is described below). If `url` is the empty string, then `open()` opens a blank window.

The `name` argument specifies a name for the new window. This name may only contain alphanumeric characters and the underscore character. It may be used as the value of the `TARGET` attribute of an `<A>` or `<FORM>` tag in HTML, to force documents to be displayed in the window.

With Navigator 3.0, when you use `Window.open()` to load a new document into a named window, you can also use the `replace` argument to specify whether the new document will have its own entry in the window's browsing history, or whether it will replace the history entry of the current document. If `replace` is `true`, the new document will replace the old. If this argument is `false` is or not specified, then the new document will have its own entry in the Window's browsing history. This argument provides functionality much like that of the `Location.replace()` method.

The `features` argument is a comma-separated list of features to appear in the window. If this optional argument is empty or not specified at all, then all features will be present in the window. On the other hand, if `features` specifies any one feature, then any features that do not appear in the list will not appear in the window. The string should not contain any spaces or other whitespace. Each element in the list has the format:

    feature[=value]

For most features, the `value` is `yes` or `no`. For these features, the equals sign and the `value` may be omitted--if the feature appears, `yes` is assumed, and if it doesn't `no` is assumed. For the `width` and `height` features, the `value` is required and must specify a size in pixels.

The available features and their meanings are listed below. Note, however, that on X11 platforms in Navigator 2.0, only the `width` and `height` features work, and new browser windows are not created with any of the standard controls, even when the `features` argument is omitted entirely.

`toolbar`

  The browser toolbar, with Back and Forward buttons, etc.

`location`

  The input field for entering URLs directly into the browser.

`directories`

  Directory buttons, such as "What's New" and "What's Cool" in Netscape.

`status`

  The status line.

`menubar`

  The menu bar.

`scrollbars`

  This feature enables horizontal and vertical scrollbars when they are necessary.

`resizable`

  If this feature is not present or is set to `no`, then the window will not have resize handles around its border. (Depending on the platform, the user may still have ways to resize the window.) Note that a common bug is to misspell this feature as "resizeable", with an extra "e".

`width`

  This feature must be followed by a value that specifies the width of the window in pixels.

`height`

  This feature must be followed by a value that specifies the height of the window in pixels.

Don't confuse this `Window.open()` method with the `document.open()` method; the two perform very different functions. For clarity in your code, you may want to use `window.open()` instead of `open()`. (Recall that the `window` property is simply a way to explicitly refer to the current window.)

## Bugs

In Navigator 2.0, on X11 and Macintosh platforms, the `url` argument is ineffective. The solution is to call `open()` once to create the window, and then call it again to set the URL, or better, to use `location` property of the new (blank) window to load the desired URL.

On X11 platforms in Navigator 2.0, only the `width` and `height` features work, and new browser windows are not created with any of the standard controls, even when the `features` argument is omitted entirely.

## See Also

"Location.replace()", "Window", "Window.close()"

Window.onunload() |  | Window.opener