A browsing context is an environment in which
objects are presented to the user.
A tab or window in a Web browser typically contains a browsing
context, as does an
A browsing context has a corresponding
A browsing context has an opener browsing context, which is null or a browsing context. It is initially null.
A browsing context has a disowned boolean. It is initially false.
A browsing context has an is closing boolean. It is initially false.
A browsing context has a session history, which lists the
Document objects that the browsing context has presented, is presenting,
or will present. A browsing context's active document is
WindowProxy object's [[Window]]
internal slot value's associated
Document's browsing context is the
browsing context whose session history contains the
Document, if any such browsing context exists and has not been discarded, and null otherwise.
In general, there is a 1-to-1 mapping from the
Window object to the
Document object, as long as the
Document object has a non-null browsing context. There is one exception. A
Window can be reused for the presentation of a second
Document in the
same browsing context, such that the mapping is then 1-to-2. This occurs when a
browsing context is navigated from the initial
Document to another, with replacement enabled.
Document does not necessarily have a non-null browsing context. In particular, data mining tools are likely
to never instantiate browsing contexts. A
Document created using an API such as
createDocument() never has a non-null browsing context. And the
created for an
iframe element, which has since been removed from the document, has no associated browsing context, since that
browsing context was discarded.
To set the active document of a browsing context
browsingContext to a
Document object document, run these
Let window be document's relevant global object.
Per this standard document can be created before window, which does not make much sense. See issue #2688.
WindowProxy object's [[Window]] internal slot value to
Set window's associated
Document to document.
Set window's relevant settings object's execution ready flag.
A browsing context has an associated creator origin (null or returns an origin), creator URL (null or returns a URL), creator base URL (null or returns a URL), and creator referrer policy (null or returns a referrer policy). These are all initially null.
Certain elements (for example,
iframe elements) can instantiate further browsing contexts. These elements are called browsing
Each browsing context container has a nested browsing context, which is either a browsing context or null.
If a browsing context is the nested browsing context of a browsing context container, then the browsing context is said to be nested through the browsing context container's node document.
A browsing context child is said to be a child browsing context of another browsing context parent, if all of the following conditions hold:
element is connected
A browsing context child is then a document-tree child browsing context of parent if it is a child browsing context and its browsing context container is not just connected, but also in a document tree.
A browsing context child may have a parent browsing context. This is the unique browsing context that has child as a child browsing context, if any such browsing context exists. Otherwise, the browsing context has no parent browsing context.
A browsing context A is said to be an ancestor of a browsing context B if there exists a browsing context A' that is a child browsing context of A and that is itself an ancestor of B, or if the browsing context A is the parent browsing context of B.
A browsing context that has no parent browsing context is the top-level browsing context for itself and all of the browsing contexts for which it is an ancestor browsing context.
A top-level browsing context has an associated group (null or a browsing context group). It is initially null.
It is possible to create new browsing contexts that are related to a top-level browsing context without being nested through an element. Such browsing contexts are called auxiliary browsing contexts. Auxiliary browsing contexts are always top-level browsing contexts.
The transitive closure of parent browsing contexts for a browsing context that is a nested browsing context gives the list of ancestor browsing contexts.
The list of the descendant browsing contexts of a
is the (ordered) list returned by the following algorithm:
Let list be an empty list.
For each child browsing context of d that is nested through an element that is in
Document d, in the tree order of the elements
nesting those browsing contexts, run these substeps:
Append that child browsing context to the list list.
Append the list of the descendant browsing contexts of the active document of that child browsing context to the list list.
Return the constructed list.
Document is said to be fully
active when its browsing context is non-null and
it is the active document of that browsing context, and either its browsing context is a top-level browsing context,
or it has a parent browsing context and the
Document through which it is nested is itself fully active.
Because they are associated with an element, child
browsing contexts are always tied to a specific
Document in their parent
browsing context. User agents must not allow the user to interact with child browsing contexts of elements that are in
that are not themselves fully active.
The following example illustrates the differences between active and fully active
Document objects. Here
a.html is loaded into a browser window,
out loaded into an
iframe as shown, and
c.html are omitted (they can simply be an empty document).
<!-- a.html --> <!DOCTYPE html> < html lang = "en" > < title >Browsing context A </ title > < iframe src = "b-1.html" ></ iframe > < button onclick = "frames.location.href = 'b-2.html'" >Click me </ button > <!-- b-1.html --> <!DOCTYPE html> < html lang = "en" > < title >Browsing context B </ title > < iframe src = "c.html" ></ iframe >
After clicking on the
button, and thus loading a new
b-2.html into browsing context B, we have the following results:
Document is still the active
document of browsing context C. However, since it is nested through the
which is itself not fully active, this means the
Document is now not fully active (even though it is active).
A browsing context that is a nested browsing context can be put into
load events mode. This is used when it is
navigated, to delay the load event of its
browsing context container before the new
Document is created.
The document family of a browsing context consists of the union of all
Document objects in that browsing context's session
history and the document families of all those
Document objects. The document family of a
consists of the union of all the document families of the
browsing contexts that are nested through the
The content document of a browsing context container container is the result of the following algorithm:
If container's nested browsing context is null, then return null.
Let context be container's nested browsing context.
Let document be context's active document.
If document's origin and the origin specified by the current settings object are not same origin-domain, then return null.
WindowProxy for the top-level browsing context.
opener[ = value ]
WindowProxy for the opener browsing context.
Returns null if there isn't one or if it has been set to null.
Can be set to null.
WindowProxy for the parent browsing context.
Element for the browsing context container.
Returns null if there isn't one, and in cross-origin situations.
Browsing contexts can have a browsing context name. Unless stated otherwise, it is the empty string.
A valid browsing context name is any string with at least one character that does not start with a U+005F LOW LINE character. (Names starting with an underscore are reserved for special keywords.)
A valid browsing context name or keyword is any string that is either a valid
browsing context name or that is an ASCII case-insensitive match for one of:
These values have different meanings based on whether the page is sandboxed or not, as
summarized in the following (non-normative) table. In this table, "current" means the
browsing context that the link or script is in, "parent" means the parent
browsing context of the one the link or script is in, "top" means the top-level
browsing context of the one the link or script is in, "new" means a new top-level
browsing context or auxiliary browsing context is to be created, subject to
various user preferences and user agent policies, "none" means that nothing will happen, and
"maybe new" means the same as "new" if the "
allow-popups" keyword is also specified on the
sandbox attribute (or if the user overrode the
sandboxing), and the same as "none" otherwise.
|Keyword||Ordinary effect||Effect in an |
|none specified, for links and form submissions||current||current||current|
|new||maybe new||maybe new|
|name that doesn't exist||new||maybe new||maybe new|
|name that exists and is a descendant||specified descendant||specified descendant||specified descendant|
|name that exists and is current||current||current||current|
|name that exists and is an ancestor that is top||specified ancestor||none||specified ancestor/top|
|name that exists and is an ancestor that is not top||specified ancestor||none||none|
|other name that exists with common top||specified||none||none|
|name that exists with different top, if familiar and one permitted sandboxed navigator||specified||specified||specified|
|name that exists with different top, if familiar but not one permitted sandboxed navigator||specified||none||none|
|name that exists with different top, not familiar||new||maybe new||maybe new|
Most of the restrictions on sandboxed browsing contexts are applied by other algorithms, e.g. the navigation algorithm, not the rules for choosing a browsing context given below.