BrowsingContext Class

Creates a top-level browsing context, whose active document is an initial about:blank document.

Gets the browsing contexts of the iframe and frame elements of the active document, in tree order (https://html.spec.whatwg.org/multipage/document-sequences.html#document-tree-child-navigables).

Gets the element that contains this browsing context (https://html.spec.whatwg.org/multipage/document-sequences.html#nav-container), or null for a top-level browsing context.

Gets the browsing context whose document created this auxiliary browsing context (window.open(), a link or a form with a _blank target), even when it has no opener (noopener, the default of the _blank links): the tab that opened the popup, as the browsers show it. It is null for the browsing contexts created by the application.

Gets the active document (https://html.spec.whatwg.org/multipage/document-sequences.html#nav-document).

Gets the event loop of the browsing context group: each top-level browsing context creates its own event loop, and the nested browsing contexts share the event loop of their top-level browsing context. The tasks of the documents (e.g. the load events, the timers and the scripts) are queued in it.

Gets or sets whether the top-level browsing context has the system focus (https://html.spec.whatwg.org/multipage/interaction.html#tlbc-system-focus): whether its window is the active window of the user. The host sets it when its window is activated or deactivated: the focused element and the window of its document get blur when the focus is lost and focus when it comes back, document.hasFocus() is false meanwhile, and the scripts still move the focus, without focus events. One top-level browsing context of a group has the system focus at a time: a new auxiliary browsing context (window.open()) takes it, and gives it back to its opener when it is closed. The nested browsing contexts share the state of their top-level browsing context. The default is true. A prerendering traversable never has the system focus (https://wicg.github.io/nav-speculation/prerendering.html#interaction-with-system-focus).

Gets the input devices of the user of the top-level browsing context: the entry point of a host application that injects the pointer and wheel input of the user (see UserInput). The nested browsing contexts share the input devices of their top-level browsing context.

Gets whether the browsing context is an auxiliary browsing context (https://html.spec.whatwg.org/multipage/document-sequences.html#auxiliary-browsing-context), created by window.open() or a _blank target.

Gets whether the browsing context was destroyed (e.g. its iframe was removed from the document).

Gets or sets whether the top-level browsing context is frozen (https://wicg.github.io/page-lifecycle/#change-the-frozenness-of-a-top-level-document): the host freezes a tab that is in the background to save resources, as the browsers do. Freezing fires the freeze event at the documents of the top-level browsing context and of its nested browsing contexts, pauses their media elements, then stops running their tasks and their timers until the browsing context is resumed (the tasks are deferred, not lost); resuming fires the resume event. The documents are updated from a task of the event loop. The nested browsing contexts share the state of their top-level browsing context. The default is false. The documents of the iframes are also frozen while their permissions policy disables execution-while-not-rendered and the iframe is not rendered, or disables execution-while-out-of-viewport and the iframe is out of the viewport.

Gets whether a navigation of the browsing context is ongoing: it started (e.g. location.href was set, or a link was followed), and its document is not active yet. It becomes false when the new document is active, and when the navigation ends without a new document (e.g. a 204 response, or a navigation canceled by another one).

Gets or sets whether the user agent is offline (as the offline option of Playwright): navigator.onLine returns false, and the offline event (or online when it changes back) is fired at the windows of the browsing context and of its nested browsing contexts. The requests are not blocked: a DocumentLoader fails them (returns null). The value is the one of the top-level browsing context.

Gets whether the browsing context was requested as a popup by the features of window.open() (https://html.spec.whatwg.org/multipage/document-sequences.html#is-popup). It only changes the visible attribute of the BarProp objects of the windows (e.g. window.menubar.visible).

Gets or sets whether the top-level browsing context is visible to the user: its system visibility state (https://html.spec.whatwg.org/multipage/interaction.html#system-visibility-state). The host sets it to false when its window is minimized, when its tab is in the background or when another window covers it: the visibility state of the documents of the top-level browsing context and of its nested browsing contexts (document.visibilityState, document.hidden) is then updated from tasks of the event loop, which fire visibilitychange. The nested browsing contexts share the state of their top-level browsing context. The default is true. A prerendering traversable is never visible (https://wicg.github.io/nav-speculation/prerendering.html#prerendering-traversable): its documents get the state of the navigable that activates them.

Gets or sets the target name (https://html.spec.whatwg.org/multipage/document-sequences.html#nav-target).

Gets the opener browsing context of an auxiliary browsing context (https://html.spec.whatwg.org/multipage/document-sequences.html#opener-browsing-context), or null.

Gets the options of the browsing context.

Gets the parent browsing context (https://html.spec.whatwg.org/multipage/document-sequences.html#nav-parent), or null for a top-level browsing context.

Gets the top-level browsing context (https://html.spec.whatwg.org/multipage/document-sequences.html#nav-top).

Gets or sets the virtual viewport of the top-level browsing context and the preferences of the user: the size of the viewport, the device pixel ratio, the media type and the user preference media features (e.g. prefers-color-scheme). It is BrowsingContextOptions.Viewport until it is set (e.g. as page.setViewportSize() and page.emulateMedia() of Playwright). A new value applies to the documents of the browsing context and of its nested browsing contexts: the media queries are evaluated again, the documents are laid out again, and the resize event is fired at the next rendering opportunity.

Gets the active window (https://html.spec.whatwg.org/multipage/document-sequences.html#nav-window).

Discards the top-level browsing context to save resources, then loads its active session history entry again, as a browser does when the user goes back to a tab that it discarded (https://wicg.github.io/page-lifecycle/#discarding): the new document has document.wasDiscarded set to true. The documents are unloaded as by a reload, and the document is loaded again by BrowsingContextOptions.DocumentLoader, from a task of the event loop.

Discards a top-level browsing context: destroys its documents and the nested browsing contexts (https://html.spec.whatwg.org/multipage/document-sequences.html#destroy-a-top-level-traversable), aborts the ongoing navigations, and disposes the event loop: the pending tasks, microtasks and timers are discarded, and the ones queued afterwards are ignored. No event is fired (use Window.Close to unload the document first).

Exits the pointer lock of the top-level browsing context, as the default unlock gesture of the user does (https://w3c.github.io/pointerlock/#dfn-default-unlock-gesture): a host calls it when its own gesture ends the lock or when the system takes the pointer back. pointerlockchange is fired by a task at the document of the pointer-lock target, which needs a user activation to lock the pointer again. The Escape key (a trusted keydown event) and the loss of the system focus (BrowsingContext.HasSystemFocus) or of the visibility (BrowsingContext.IsVisible) exit the pointer lock too.

Reloads the active document, as the reload button of a browser (https://html.spec.whatwg.org/multipage/browsing-the-web.html#reload, with the "browser UI" user navigation involvement: the navigate event of the navigation API cannot cancel it). The document is loaded again by BrowsingContextOptions.DocumentLoader, from a task of the event loop.

Closes a top-level browsing context as the user closes the tab of a browser (https://html.spec.whatwg.org/multipage/document-sequences.html#close-a-top-level-traversable): the beforeunload event is fired (when runBeforeUnload is true; the user can cancel the closing, see BrowsingContextOptions.UserPromptHandler), then the documents are unloaded (pagehide and unload) and destroyed (BrowsingContextOptions.BrowsingContextDestroyed is invoked). Unlike BrowsingContext.Dispose, the event loop of the browsing context group is not disposed: the other top-level browsing contexts of the group (the auxiliary browsing contexts) keep running.