search
element with form functionality — Last Updated 1 December 2021A browsing context is an environment in which Document
objects
are presented to the user.
A tab or window in a web browser typically contains a browsing
context, as does an iframe
.
A browsing context has a corresponding WindowProxy
object.
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.
The following example illustrates the various possibilities of a browsing context. It can be disowned, is closing, neither, or both.
// Neither disowned nor is closing:
const popup1 = window. open();
// Disowned, but not is closing:
const popup2 = window. open();
popup2. opener = null ;
// Not disowned, but is closing:
const popup3 = window. open();
popup3. close();
// Disowned, is closing:
const popup4 = window. open();
popup4. opener = null ;
popup4. close();
A browsing context has a session history, which lists the
Document
objects that the browsing context has presented, is presenting,
or will present. A 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.
A 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 Document
originally
created for an iframe
element, which has since been removed from the document, has no associated browsing context, since that
browsing context was discarded.
A browsing context's active window is its
WindowProxy
object's [[Window]]
internal slot value. A browsing context's active document is its
active window's associated
Document
.
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 about:blank
Document
to
another, with historyHandling set to "replace
".
A browsing context has a virtual browsing context group ID integer. It is initially 0. This is used by cross-origin opener policy reporting, to keep track of the browsing context group switches that would have happened if the report-only policy had been enforced.
A browsing context has an initial URL, which is a URL or null. It is initially null.
A browsing context has an opener origin at creation, which is an origin or null. It is initially null.
To set the active document of a browsing context
browsingContext to a Document
object document, run these
steps:
Let window be document's relevant global object.
Set document's visibility state to browsingContext's top-level browsing context's system visibility state.
Set browsingContext's active window to window.
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), and creator base URL (null or returns a URL). These are all initially null.
Certain elements (for example, iframe
elements) can instantiate further browsing contexts. These elements are called browsing context
containers.
Each browsing context container has a nested browsing context, which is either a browsing context or null. It is initially null.
The container of a browsing context bc is the browsing context container whose nested browsing context is bc, or null if there is no such element.
Each browsing context bc has a container document, which is the result of running these steps:
If bc's container is null, then return null.
Return bc's container's node document.
This is equal to bc's container's shadow-including root as bc's container has to be connected.
A browsing context child is said to be a child browsing context of another browsing context parent, if child's container document is non-null and child's container document's browsing context is parent.
A browsing context child is a document-tree child browsing context of parent if child is a child browsing context and child's container is 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.
A top-level browsing context has an is popup boolean. It is initially false.
The only mandatory impact in this specification of is popup is on the
visible
getter of the relevant BarProp
objects. However, user agents might also use it in the following ways:
In both cases user agents might additionally incorporate user preferences, or present a choice as to whether to go down the popup route.
User agents that provides a minimal web browser user interface for such popups are encouraged to not hide the browser's location bar.
It is possible to create new browsing contexts that are related to a top-level browsing context while their container is null. 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 child browsing context gives the list of ancestor browsing contexts.
The list of the descendant browsing contexts of a Document
d
is the (ordered) list returned by the following algorithm:
Let list be an empty list.
For each browsing context container container, whose nested browsing context is non-null and whose shadow-including root is d, in shadow-including tree order:
Let nestedBC be container's nested browsing context.
Append nestedBC to list.
Extend list with the list of the descendant browsing contexts of nestedBC's active document.
Return list.
A Document
d is said to be fully
active when d's browsing context is
non-null, d's browsing context's active
document is d, and either d's browsing context is a top-level browsing context,
or d's browsing context's container document is 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 Document
s
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, b-1.html
starts
out loaded into an iframe
as shown, and b-2.html
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[0].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 >
At this point, the documents given by a.html
, b-1.html
, and c.html
are all the active documents of their respective browsing
contexts. They are also all fully active.
After clicking on the button
, and thus loading a new Document
from
b-2.html
into browsing context B, we have the following results:
The a.html
Document
remains both the active
document of browsing context A, and fully active.
The b-1.html
Document
is now not the
active document of browsing context B. As such it is also not fully
active.
The new b-2.html
Document
is now the active
document of browsing context B, and is also fully active.
The c.html
Document
is still the active
document of browsing context C. However, since C's container document is the b-1.html
Document
, which is itself not fully active, this means the c.html
Document
is now not fully active (even though
it is active).
For more explorations of the complexities involved here, especially as it impacts the session history, see A Model of Navigation History. [NAVMODEL]
A child browsing context can be put into a delaying load
events mode. This is used when it is navigated, to delay the load event of its
container before the new Document
is created.
The document family of a browsing context consists of the union of all
the Document
objects in that browsing context's session
history and the document families of all those
Document
objects. The document family of a Document
object
consists of the union of all the document families of the
browsing contexts in the list of the descendant
browsing contexts of the Document
object.
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 container's node document's origin are not same origin-domain, then return null.
Return document.
window.top
Returns the WindowProxy
for the top-level browsing
context.
window.opener [ = value ]
Returns the 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.
window.parent
Returns the WindowProxy
for the parent browsing
context.
window.frameElement
Returns the 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:
_blank
, _self
, _parent
, or
_top
.
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 iframe with...
| |
---|---|---|---|
sandbox=""
| sandbox="allow-top-navigation"
| ||
none specified, for links and form submissions | current | current | current |
empty string | current | current | current |
_blank
| new | maybe new | maybe new |
_self
| current | current | current |
_parent if there isn't a parent
| current | current | current |
_parent if parent is also top
| parent/top | none | parent/top |
_parent if there is one and it's not top
| parent | none | none |
_top if top is current
| current | current | current |
_top if top is not current
| top | none | top |
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.