HTML: The Living Standard

Developer's Edition — Last Updated 14 September 2017

About this specification

This specification is like no other — it has been processed with you, the humble web developer, in mind.

The focus of this specification is readability and ease of access. Unlike the full HTML Standard, this "developer's edition" removes information that only browser vendors need know. It is automatically produced from the full specification by our build tooling, and thus always in sync with the latest developments in HTML.

To read about its conception, construction, and future, read the original press release, and the blog post about its relaunch.

Finally, feel free to contribute on GitHub to make this edition better for everyone!

1. 7 Loading Web pages
   1. 7.1 Browsing contexts
      1. 7.1.1 Nested browsing contexts
         1. 7.1.1.1 Navigating nested browsing contexts in the DOM
      2. 7.1.2 Auxiliary browsing contexts
         1. 7.1.2.1 Navigating auxiliary browsing contexts in the DOM
      3. 7.1.3 Browsing context names

7 Loading Web pages

7.1 Browsing contexts

A 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 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 its WindowProxy object's [[Window]] internal slot value's associated Document. 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.

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 browsing context. There are two exceptions. First, 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 replacement enabled. Second, a Document can end up being reused for several Window objects when the document.open() method is used, such that the mapping is then many-to-1.

A Document does not necessarily have a browsing context associated with it. In particular, data mining tools are likely to never instantiate browsing contexts. A Document created using an API such as createDocument() never has a 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.

To set the active document of a browsing context browsingContext to a Document object document, optionally with a Window object window, run these steps:

1. If window is not given, 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.

2. Set browsingContext's WindowProxy object's [[Window]] internal slot value to window.

3. Set window's associated Document to document.

4. Set window's relevant settings object's execution ready flag.

A browsing context can have a creator browsing context, the browsing context that was responsible for its creation. If a browsing context has a parent browsing context, then that is its creator browsing context. Otherwise, if the browsing context has an opener browsing context, then that is its creator browsing context. Otherwise, the browsing context has no creator browsing context.

If a browsing context context has a creator browsing context creator, it also has the following properties. In what follows, let creator document be creator's active document at the time context is created:

creator origin

creator document's origin

creator URL

creator document's URL

creator base URL

creator document's base URL

creator referrer policy

creator document's referrer policy

creator context security

The result of executing Is environment settings object a secure context? on creator document's relevant settings object

7.1.1 Nested browsing contexts

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.

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:

• child is a nested browsing context of a browsing context container element

• element is connected

• element's shadow-including root's browsing context is parent

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 is not a nested browsing context has no parent browsing context, and is the top-level browsing context of all the browsing contexts for which it is an ancestor browsing context.

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 Document d is the (ordered) list returned by the following algorithm:

1. Let list be an empty list.

2. For each child browsing context of d that is nested through an element that is in the Document d, in the tree order of the elements nesting those browsing contexts, run these substeps:

   1. Append that child browsing context to the list list.

   2. Append the list of the descendant browsing contexts of the active document of that child browsing context to the list list.

3. Return the constructed list.

A Document is said to be fully active when it has a browsing context 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 Documents that are not themselves fully active.

A browsing context that is a nested 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 browsing context 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 that are nested through the Document object.

The content document of a browsing context container container is the result of the following algorithm:

1. If container's nested browsing context is null, then return null.

2. Let context be container's nested browsing context.

3. Let document be context's active document.

4. If document's origin and the origin specified by the current settings object are not same origin-domain, then return null.

5. Return document.

7.1.1.1 Navigating nested browsing contexts in the DOM

window . top

Returns the WindowProxy for the top-level browsing context.

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.

7.1.2 Auxiliary browsing contexts

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.

An auxiliary browsing context has an opener browsing context, which is the browsing context from which the auxiliary browsing context was created.

7.1.2.1 Navigating auxiliary browsing contexts in the DOM

The opener IDL attribute on the Window object, on getting, must return the WindowProxy object of the browsing context from which the current browsing context was created (its opener browsing context), if there is one, if it is still available, and if the current browsing context has not disowned its opener; otherwise, it must return null. On setting, if the new value is null then the current browsing context must disown its opener; if the new value is anything else then the user agent must call the [[DefineOwnProperty]] internal method of the Window object, passing the property name "opener" as the property key, and the Property Descriptor { [[Value]]: value, [[Writable]]: true, [[Enumerable]]: true, [[Configurable]]: true } as the property descriptor, where value is the new value.

7.1.3 Browsing context names

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.

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.