search element with form functionality — Last Updated 1 December 2021Window objectSupport in all current engines.
[Global =Window ,
Exposed =Window ,
LegacyUnenumerableNamedProperties ]
interface Window : EventTarget {
// the current browsing context
[LegacyUnforgeable ] readonly attribute WindowProxy window ;
[Replaceable ] readonly attribute WindowProxy self ;
[LegacyUnforgeable ] readonly attribute Document document ;
attribute DOMString name ;
[PutForwards =href , LegacyUnforgeable ] readonly attribute Location location ;
readonly attribute History history ;
readonly attribute CustomElementRegistry customElements ;
[Replaceable ] readonly attribute BarProp locationbar ;
[Replaceable ] readonly attribute BarProp menubar ;
[Replaceable ] readonly attribute BarProp personalbar ;
[Replaceable ] readonly attribute BarProp scrollbars ;
[Replaceable ] readonly attribute BarProp statusbar ;
[Replaceable ] readonly attribute BarProp toolbar ;
attribute DOMString status ;
undefined close ();
readonly attribute boolean closed ;
undefined stop ();
undefined focus ();
undefined blur ();
// other browsing contexts
[Replaceable ] readonly attribute WindowProxy frames ;
[Replaceable ] readonly attribute unsigned long length ;
[LegacyUnforgeable ] readonly attribute WindowProxy ? top ;
attribute any opener ;
[Replaceable ] readonly attribute WindowProxy ? parent ;
readonly attribute Element ? frameElement ;
WindowProxy ? open (optional USVString url = "", optional DOMString target = "_blank", optional [LegacyNullToEmptyString ] DOMString features = "");
getter object (DOMString name );
// Since this is the global object, the IDL named getter adds a NamedPropertiesObject exotic
// object on the prototype chain. Indeed, this does not make the global object an exotic object.
// Indexed access is taken care of by the WindowProxy exotic object.
// the user agent
readonly attribute Navigator navigator ;
readonly attribute Navigator clientInformation ; // legacy alias of .navigator
readonly attribute boolean originAgentCluster ;
// user prompts
undefined alert ();
undefined alert (DOMString message );
boolean confirm (optional DOMString message = "");
DOMString ? prompt (optional DOMString message = "", optional DOMString default = "");
undefined print ();
undefined postMessage (any message , USVString targetOrigin , optional sequence <object > transfer = []);
undefined postMessage (any message , optional WindowPostMessageOptions options = {});
// also has obsolete members
};
Window includes GlobalEventHandlers ;
Window includes WindowEventHandlers ;
dictionary WindowPostMessageOptions : StructuredSerializeOptions {
USVString targetOrigin = "/";
};window.windowSupport in all current engines.
window.framesSupport in all current engines.
window.selfSupport in all current engines.
These attributes all return window.
window.documentSupport in all current engines.
Returns the Document associated with window.
document.defaultViewSupport in all current engines.
Returns the Window object of the active document.
The Window object has an associated
Document, which is a Document object. It is set when the
Window object is created, and only ever changed during navigation from the initial
about:blank Document.
The Window object's browsing
context is the Window object's associated Document's browsing context. It is either null or a
browsing context.
The window, frames, and self attributes' getters must return this Window
object's relevant Realm.[[GlobalEnv]]'s
EnvironmentRecord's [[GlobalThisValue]].
The document IDL
attribute, on getting, must return this Window object's associated Document.
The Document object associated with a Window object can
change in exactly one case: when the navigate algorithm creates a new Document object for the
first page loaded in a browsing context. In that specific case, the
Window object of the initial
about:blank page is reused and gets a new Document object.
The defaultView attribute's getter, when invoked, must
run these steps:
If this Document object's browsing
context is null, then return null.
Return this Document object's browsing
context's WindowProxy object.
Support in all current engines.
For historical reasons, Window objects must also have a writable, configurable,
non-enumerable property named HTMLDocument whose value is the
Document interface object.
window = window.open([ url [, target [, features ] ] ])Support in all current engines.
Opens a window to show url (defaults to "about:blank"), and returns
it. target (defaults to "_blank") gives the name of the new
window. If a window already exists with that name, it is reused. The features
argument can contain a set of comma-separated tokens:
noopener"noreferrer"These behave equivalently to the noopener and noreferrer link types on hyperlinks.
popup"Encourages user agents to provide a minimal web browser user interface for the new
window. (Impacts the visible getter on all
BarProp objects as well.)
globalThis. open( "https://email.example/message/CAOOOkFcWW97r8yg=SsWg7GgCmp4suVX9o85y8BvNRqMjuc5PXg" , undefined , "noopener,popup" ); window.name [ = value ]Support in all current engines.
Returns the name of the window.
Can be set, to change the name.
window.close()Support in all current engines.
Closes the window.
window.closedSupport in all current engines.
Returns true if the window has been closed, false otherwise.
window.stop()Support in all current engines.
Cancels the document load.
The window open steps, given a string url, a string target, and a string features, are as follows:
If the event loop's termination nesting level is nonzero, return null.
Let source browsing context be the entry global object's browsing context.
If target is the empty string, then set target to "_blank".
Let tokenizedFeatures be the result of tokenizing features.
Let noopener and noreferrer be false.
If tokenizedFeatures["noopener"] exists, then:
Set noopener to the result of parsing tokenizedFeatures["noopener"] as a boolean feature.
Remove tokenizedFeatures["noopener"].
If tokenizedFeatures["noreferrer"] exists, then:
Set noreferrer to the result of parsing tokenizedFeatures["noreferrer"] as a boolean feature.
Remove tokenizedFeatures["noreferrer"].
If noreferrer is true, then set noopener to true.
Let target browsing context and windowType be the result of applying the rules for choosing a browsing context given target, source browsing context, and noopener.
If there is a user agent that supports control-clicking a link to open it in
a new tab, and the user control-clicks on an element whose onclick handler uses the window.open() API to open a page in an iframe element, the
user agent could override the selection of the target browsing context to instead target a new
tab.
If target browsing context is null, then return null.
If windowType is either "new and unrestricted" or "new with no opener", then:
Set the target browsing context's is popup to the result of checking if a popup window is requested, given tokenizedFeatures.
Set up browsing context features for target browsing context given tokenizedFeatures. [CSSOMVIEW]
Let urlRecord be the URL record
about:blank.
If url is not the empty string, then parse
url relative to the entry settings object, and set urlRecord
to the resulting URL record, if any. If the parse a URL algorithm
failed, then throw a "SyntaxError"
DOMException.
If urlRecord matches about:blank, then perform the
URL and history update steps given target browsing context's
active document and urlRecord.
This is necessary in case url is something like about:blank?foo. If url is just plain about:blank, this will do nothing.
Otherwise:
If noreferrer is true, then set request's referrer to "no-referrer".
Navigate target browsing context to
request, with exceptionsEnabled set to true, historyHandling set to "replace", and the source browsing context set to
source browsing context.
Otherwise:
If url is not the empty string, then:
Let urlRecord be the URL record
about:blank.
Parse url relative to the entry
settings object, and set urlRecord to the resulting URL
record, if any. If the parse a URL algorithm failed, then throw a
"SyntaxError" DOMException.
If noreferrer is true, then set request's referrer to "noreferrer".
Navigate target browsing context to request, with exceptionsEnabled set to true and the source browsing context set to source browsing context.
If noopener is false, then set target browsing context's opener browsing context to source browsing context.
If noopener is true or windowType is "new with no opener", then return null.
Return target browsing context's WindowProxy object.
The open(url, target,
features) method on Window objects provides a mechanism for
navigating an existing browsing context or opening and
navigating an auxiliary browsing context.
When the method is invoked, the user agent must run the window open steps with url, target, and features.
To tokenize the features argument:
Let tokenizedFeatures be a new ordered map.
Let position point at the first code point of features.
While position is not past the end of features:
Let name be the empty string.
Let value be the empty string.
Collect a sequence of code points that are feature separators from features given position. This skips past leading separators before the name.
Collect a sequence of code points that are not feature separators from features given position. Set name to the collected characters, converted to ASCII lowercase.
Set name to the result of normalizing the feature name name.
While position is not past the end of features and the code point at position in features is not U+003D (=):
If the code point at position in features is U+002C (,), or if it is not a feature separator, then break.
Advance position by 1.
This skips to the first U+003D (=) but does not skip past a U+002C (,) or a non-separator.
If the code point at position in features is a feature separator:
While position is not past the end of features and the code point at position in features is a feature separator:
If the code point at position in features is U+002C (,), then break.
Advance position by 1.
This skips to the first non-separator but does not skip past a U+002C (,).
Collect a sequence of code points that are not feature separators code points from features given position. Set value to the collected code points, converted to ASCII lowercase.
If name is not the empty string, then set tokenizedFeatures[name] to value.
Return tokenizedFeatures.
To check if a window feature is set, given tokenizedFeatures, featureName, and defaultValue:
If tokenizedFeatures[featureName] exists, then return the result of parsing tokenizedFeatures[featureName] as a boolean feature.
Return defaultValue.
To check if a popup window is requested, given tokenizedFeatures:
If tokenizedFeatures is empty, then return false.
If tokenizedFeatures["popup"] exists, then return the result of parsing
tokenizedFeatures["popup"] as a boolean
feature.
Let location be the result of checking if
a window feature is set, given tokenizedFeatures, "location", and false.
Let toolbar be the result of checking if
a window feature is set, given tokenizedFeatures, "toolbar", and false.
If location and toolbar are both false, then return true.
Let menubar be the result of checking if
a window feature is set, given tokenizedFeatures, menubar", and false.
If menubar is false, then return true.
Let resizable be the result of checking if
a window feature is set, given tokenizedFeatures, "resizable", and true.
If resizable is false, then return true.
Let scrollbars be the result of checking
if a window feature is set, given tokenizedFeatures, "scrollbars", and false.
If scrollbars is false, then return true.
Let status be the result of checking if
a window feature is set, given tokenizedFeatures, "status", and false.
If status is false, then return true.
Return false.
A code point is a feature separator if it is ASCII whitespace, U+003D (=), or U+002C (,).
For legacy reasons, there are some aliases of some feature names. To normalize a feature name name, switch on name:
screenx"
left".
screeny"
top".
innerwidth"
width".
innerheight"
height".
To parse a boolean feature given a string value:
If value is the empty string, then return true.
If value is "yes", then return
true.
Let parsed be the result of parsing value as an integer.
If parsed is an error, then set it to 0.
Return false if parsed is 0, and true otherwise.
The name getter steps are:
If this's browsing context is null, then return the empty string.
Return this's browsing context's name.
The name setter steps are:
If this's browsing context is null, then return.
Set this's browsing context's name to the given value.
The name gets reset when the browsing context is navigated to another origin.
The close() method steps
are:
Let current be this's browsing context.
If current is null or its is closing is true, then return.
If all the following are true
then:
Set current's is closing to true.
Queue a task on the DOM manipulation task source to close current.
A browsing context is script-closable if it is an auxiliary
browsing context that was created by a script (as opposed to by an action of the user), or
if it is a top-level browsing context whose session history contains
only one Document.
The closed getter
steps are to return true if this's browsing context
is null or its is closing is true; otherwise false.
The stop() method steps
are to stop document loading given this's associated Document.
window.lengthSupport in all current engines.
Returns the number of document-tree child browsing contexts.
window[index]Returns the indicated document-tree child browsing context.
The number of document-tree child browsing
contexts of a Window object W is the result of running these
steps:
If W's browsing context is null, then return 0.
Return the number of document-tree child browsing contexts of W's browsing context.
The length getter steps are
to return the number of document-tree child browsing contexts of
this.
Indexed access to document-tree child browsing contexts is defined through the [[GetOwnProperty]] internal method of the
WindowProxy object.
Window objectwindow[name]Returns the indicated element or collection of elements.
As a general rule, relying on this will lead to brittle code. Which IDs end up mapping to
this API can vary over time, as new features are added to the web platform, for example. Instead
of this, use document.getElementById() or document.querySelector().
The document-tree child browsing context
name property set of a Window object window is the return value of
running these steps:
If window's browsing context is null, then return the empty list.
Let childBrowsingContexts be all document-tree child browsing contexts of window's browsing context whose browsing context name is not the empty string, in order, and including only the first document-tree child browsing context with a given name if multiple document-tree child browsing contexts have the same one.
Remove each browsing context from childBrowsingContexts whose
active document's origin is not
same origin with window's relevant settings object's origin and whose browsing context
name does not match the name of its container's name content attribute value.
Return the browsing context names of childBrowsingContexts, in the same order.
This means that in the following example, hosted on https://example.org/, assuming https://elsewhere.example/
sets window.name to "spices", evaluating
window.spices after everything has loaded will yield undefined:
< iframe src = https://elsewhere.example.com/ ></ iframe >
< iframe name = spices ></ iframe > The Window object supports named
properties. The supported property names of a Window object
window at any moment consist of the following, in tree order according to
the element that contributed them, ignoring later duplicates:
window's document-tree child browsing context name property set;
the value of the name content attribute for all embed,
form, search, img, and object elements that
have a non-empty name content attribute and are in a document
tree with window's associated
Document as their root; and
the value of the id content attribute for all HTML
elements that have a non-empty id content attribute and are
in a document tree with window's associated Document as their
root.
To determine the value of a named property
name in a Window object window, the user agent must return the
value obtained using the following steps:
Let objects be the list of named objects of window with the name name.
There will be at least one such object, by definition.
If objects contains a browsing context, then return the
WindowProxy object of the nested browsing context of the first
browsing context container in tree order whose nested browsing
context is in objects.
Otherwise, if objects has only one element, return that element.
Otherwise return an HTMLCollection rooted at window's associated Document, whose filter matches
only named objects of window with
the name name. (By definition, these will all be elements.)
Named objects of Window object
window with the name name, for the purposes of the above algorithm, consist
of the following:
document-tree child browsing
contexts of window's associated
Document whose name is
name;
embed, form, search, img, or
object elements that have a name content attribute whose
value is name and are in a document tree with window's associated Document as their
root; and
HTML elements that have an id content attribute
whose value is name and are in a document tree with window's
associated Document as their
root.
To discard a
Document document:
Set document's salvageable state to false.
Run any unloading document cleanup steps for document that are defined by this specification and other applicable specifications.
Abort document.
Remove any tasks associated with document in any task source, without running those tasks.
Discard all the child browsing contexts of document.
For each session history entry entry whose document is equal to document, set entry's document to null.
Set document's browsing context to null.
Remove document from the
owner set of each WorkerGlobalScope object whose set contains document.
For each workletGlobalScope in document's worklet global scopes, terminate workletGlobalScope.
To discard a browsing context browsingContext, run these steps:
Discard all Document objects for all
the entries in browsingContext's session history.
If browsingContext is a top-level browsing context, then remove browsingContext.
User agents may discard top-level browsing contexts at any time (typically, in
response to user requests, e.g., when a user force-closes a window containing one or more top-level browsing contexts). Other browsing contexts must be discarded once their
WindowProxy object is eligible for garbage collection, in addition to the other
places where this specification requires them to be discarded.
To close a browsing context browsingContext, run these steps:
If the result of calling prompt to unload with browsingContext's
active document is "refuse", then return.
Unload browsingContext's active document.
Remove browsingContext from the user interface (e.g., close or hide its tab in a tabbed browser).
Discard browsingContext.
User agents should offer users the ability to arbitrarily close any top-level browsing context.
For historical reasons, the Window interface had some attributes that represented
the visibility of certain web browser interface elements.
For privacy and interoperability reasons, those attributes now return values that represent
whether the Window's browsing context's is
popup property is true or false.
Each interface element is represented by a BarProp object:
Support in all current engines.
[Exposed =Window ]
interface BarProp {
readonly attribute boolean visible ;
};window.locationbar.visibleSupport in all current engines.
window.menubar.visibleSupport in all current engines.
window.personalbar.visibleSupport in all current engines.
window.scrollbars.visibleSupport in all current engines.
window.statusbar.visibleSupport in all current engines.
window.toolbar.visibleSupport in all current engines.
Returns true if the top-level browsing context is not a popup; otherwise, returns false.
Support in all current engines.
The visible getter steps are:
Let browsingContext be this's relevant global object's browsing context.
If browsingContext is null, then return true.
Return the negation of browsingContext's top-level browsing context's is popup.
The following BarProp objects must exist for each Window object:
BarProp objectBarProp objectBarProp objectBarProp objectBarProp objectBarProp objectThe locationbar
attribute must return the location bar BarProp object.
The menubar
attribute must return the menu bar BarProp object.
The personalbar
attribute must return the personal bar BarProp object.
The scrollbars
attribute must return the scrollbar BarProp object.
The statusbar
attribute must return the status bar BarProp object.
The toolbar
attribute must return the toolbar BarProp object.
For historical reasons, the status attribute on the Window object must,
on getting, return the last string it was set to, and on setting, must set itself to the new
value. When the Window object is created, the attribute must be set to the empty
string. It does not do anything else.
Window objectsTo set up a window environment settings object, given a URL creationURL, a JavaScript execution context execution context, null or an environment reservedEnvironment, a URL topLevelCreationURL, and an origin topLevelOrigin, run these steps:
Let realm be the value of execution context's Realm component.
Let window be realm's global object.
Let settings object be a new environment settings object whose algorithms are defined as follows:
Return execution context.
Return the module map of
window's associated
Document.
Return window's associated
Document.
Return the current character encoding
of window's associated
Document.
Return the current base URL of window's
associated Document.
Return the origin of window's
associated Document.
Return the policy container of
window's associated
Document.
Return true if both of the following hold, and false otherwise:
realm's agent cluster's cross-origin-isolation mode is "concrete", and
window's associated
Document is allowed to use the "cross-origin-isolated" feature.
Return window's associated
Document's load timing info's navigation start
time.
If reservedEnvironment is non-null, then:
Set settings object's id to reservedEnvironment's id, target browsing context to reservedEnvironment's target browsing context, and active service worker to reservedEnvironment's active service worker.
Set reservedEnvironment's id to the empty string.
The identity of the reserved environment is considered to be fully transferred to the created environment settings object. The reserved environment is not searchable by the environment’s id from this point on.
Otherwise, set settings object's id to a new unique opaque string, settings object's target browsing context to null, and settings object's active service worker to null.
Set settings object's creation URL to creationURL, settings object's top-level creation URL to topLevelCreationURL, and settings object's top-level origin to topLevelOrigin.
Set realm's [[HostDefined]] field to settings object.
WindowProxy exotic objectA WindowProxy is an exotic object that wraps a
Window ordinary object, indirecting most operations through to the wrapped object.
Each browsing context has an associated WindowProxy object. When the
browsing context is navigated, the Window
object wrapped by the browsing context's associated WindowProxy object
is changed.
The WindowProxy exotic object must use the ordinary internal methods except where
it is explicitly specified otherwise below.
There is no WindowProxy interface object.
Every WindowProxy object has a [[Window]] internal slot representing the wrapped Window object.
Although WindowProxy is named as a "proxy", it does not do
polymorphic dispatch on its target's internal methods as a real proxy would, due to a desire to
reuse machinery between WindowProxy and Location objects. As long as the
Window object remains an ordinary object this is unobservable and can be implemented
either way.
Let W be the value of the [[Window]] internal slot of this.
If ! IsPlatformObjectSameOrigin(W) is true, then return ! OrdinaryGetPrototypeOf(W).
Return null.
Return ! SetImmutablePrototype(this, V).
Return true.
Return false.
Let W be the value of the [[Window]] internal slot of this.
If P is an array index property name, then:
Let index be ! ToUint32(P).
Let maxProperties be the number of document-tree child browsing contexts of W.
Let value be undefined.
If maxProperties is greater than 0 and index is less than
maxProperties, then set value to the WindowProxy object of
the indexth document-tree child browsing context of W's
browsing context, sorted in the order that their browsing context container elements were most
recently inserted into W's associated
Document, the WindowProxy object of the most recently inserted
browsing context container's nested browsing context being
last.
If value is undefined, then:
If ! IsPlatformObjectSameOrigin(W) is true, then return undefined.
Throw a "SecurityError" DOMException.
Return PropertyDescriptor{ [[Value]]: value, [[Writable]]: false, [[Enumerable]]: true, [[Configurable]]: true }.
If ! IsPlatformObjectSameOrigin(W) is true, then return ! OrdinaryGetOwnProperty(W, P).
This is a willful violation of the JavaScript specification's invariants of the essential internal methods to maintain compatibility with existing web content. See tc39/ecma262 issue #672 for more information. [JAVASCRIPT]
Let property be ! CrossOriginGetOwnPropertyHelper(W, P).
If property is not undefined, then return property.
If property is undefined and P is in W's document-tree child browsing context name property set, then:
Let value be the WindowProxy object of the named object of W with the name
P.
Return PropertyDescriptor{ [[Value]]: value, [[Enumerable]]: false, [[Writable]]: false, [[Configurable]]: true }.
The reason the property descriptors are non-enumerable, despite this mismatching the same-origin behavior, is for compatibility with existing web content. See issue #3183 for details.
Return ? CrossOriginPropertyFallback(P).
Let W be the value of the [[Window]] internal slot of this.
If ! IsPlatformObjectSameOrigin(W) is true, then:
If P is an array index property name, return false.
Return ? OrdinaryDefineOwnProperty(W, P, Desc).
This is a willful violation of the JavaScript specification's invariants of the essential internal methods to maintain compatibility with existing web content. See tc39/ecma262 issue #672 for more information. [JAVASCRIPT]
Throw a "SecurityError" DOMException.
Let W be the value of the [[Window]] internal slot of this.
Check if an access between two browsing contexts should be reported, given the current global object's browsing context, W's browsing context, P, and the current settings object.
If ! IsPlatformObjectSameOrigin(W) is true, then return ? OrdinaryGet(this, P, Receiver).
Return ? CrossOriginGet(this, P, Receiver).
this is passed rather than W as OrdinaryGet and CrossOriginGet will invoke the [[GetOwnProperty]] internal method.
Let W be the value of the [[Window]] internal slot of this.
Check if an access between two browsing contexts should be reported, given the current global object's browsing context, W's browsing context, P, and the current settings object.
If ! IsPlatformObjectSameOrigin(W) is true, then:
If P is an array index property name, then return false.
Return ? OrdinarySet(W, P, V, Receiver).
Return ? CrossOriginSet(this, P, V, Receiver).
this is passed rather than W as CrossOriginSet will invoke the [[GetOwnProperty]] internal method.
Let W be the value of the [[Window]] internal slot of this.
If ! IsPlatformObjectSameOrigin(W) is true, then:
If P is an array index property name, then:
Let desc be ! this.[[GetOwnProperty]](P).
If desc is undefined, then return true.
Return false.
Return ? OrdinaryDelete(W, P).
Throw a "SecurityError" DOMException.
Let W be the value of the [[Window]] internal slot of this.
Let keys be a new empty List.
Let maxProperties be the number of document-tree child browsing contexts of W.
Let index be 0.
Repeat while index < maxProperties,
Add ! ToString(index) as the last element of keys.
Increment index by 1.
If ! IsPlatformObjectSameOrigin(W) is true, then return the concatenation of keys and ! OrdinaryOwnPropertyKeys(W).
Return the concatenation of keys and ! CrossOriginOwnPropertyKeys(W).