Living Standard — Last Updated 27 September 2023
Window,
WindowProxy, and Location objectsWindow objectWindowProxy exotic objectLocation interfaceHistory interfaceWindow,
WindowProxy, and Location objectsAlthough typically objects cannot be accessed across origins, the web platform would not be true to itself if it did not have some legacy exceptions to that rule that the web depends upon.
This section uses the terminology and typographic conventions from the JavaScript specification. [JAVASCRIPT]
When perform a security check is invoked, with a platformObject, identifier, and type, run these steps:
If platformObject is not a Window or Location object,
then return.
For each e of CrossOriginProperties(platformObject):
If SameValue(e.[[Property]], identifier) is true, then:
If type is "method" and e has neither
[[NeedsGet]] nor [[NeedsSet]], then return.
Otherwise, if type is "getter" and
e.[[NeedsGet]] is true, then return.
Otherwise, if type is "setter" and
e.[[NeedsSet]] is true, then return.
If IsPlatformObjectSameOrigin(platformObject) is false, then
throw a " The [[CrossOriginPropertyDescriptorMap]] internal slot contains a map
with entries whose keys are (currentGlobal, objectGlobal,
propertyKey)-tuples and values are property descriptors, as a memoization of what is
visible to scripts when currentGlobal inspects a User agents should allow a value held in the map to be garbage collected along with its
corresponding key when nothing holds a reference to any part of the value. That is, as long as
garbage collection is not observable. For example, with User agents may have an optimization whereby they remove key-value pairs from the map when
For example, setting If O is a Return «
{ [[Property]]: " This abstract operation does not return a Completion Record. Indexed properties do not need to be safelisted in this algorithm, as they are
handled directly by the A JavaScript property name P is a cross-origin accessible window property
name if it is " If P is " Throw a " Return true if the current settings object's origin is same origin-domain with
O's relevant settings object's origin, and false otherwise. This abstract operation does not return a Completion Record. Here the current settings object roughly corresponds to the "caller",
because this check occurs before the execution
context for the getter/setter/method in question makes its way onto the JavaScript
execution context stack. For example, in the code If this abstract operation returns undefined and there is no custom behavior, the
caller needs to throw a " Let crossOriginKey be a tuple consisting of the current settings
object, O's relevant settings object, and P. For each e of CrossOriginProperties(O): If SameValue(e.[[Property]], P) is true, then: If the value of the [[CrossOriginPropertyDescriptorMap]] internal slot of
O contains an entry whose key is crossOriginKey, then return that
entry's value. Let originalDesc be OrdinaryGetOwnProperty(O,
P). Let crossOriginDesc be undefined. If e.[[NeedsGet]] and e.[[NeedsSet]] are absent, then: Let value be originalDesc.[[Value]]. If IsCallable(value) is true, then set value to
an anonymous built-in function, created in the current realm, that performs
the same steps as the IDL operation P on object O. Set crossOriginDesc to PropertyDescriptor{
[[Value]]: value,
[[Enumerable]]: false,
[[Writable]]: false,
[[Configurable]]: true }. Otherwise: Let crossOriginGet be undefined. If e.[[NeedsGet]] is true, then set crossOriginGet to an
anonymous built-in function, created in the current realm, that performs the
same steps as the getter of the IDL attribute P on object
O. Let crossOriginSet be undefined. If e.[[NeedsSet]] is true, then set crossOriginSet to an
anonymous built-in function, created in the current realm, that performs the
same steps as the setter of the IDL attribute P on object
O. Set crossOriginDesc to PropertyDescriptor{
[[Get]]: crossOriginGet,
[[Set]]: crossOriginSet,
[[Enumerable]]: false,
[[Configurable]]: true }. Create an entry in the value of the [[CrossOriginPropertyDescriptorMap]]
internal slot of O with key crossOriginKey and value
crossOriginDesc. Return crossOriginDesc. Return undefined. This abstract operation does not return a Completion Record. The reason that the property descriptors produced here are configurable is to
preserve the invariants of the essential internal methods required by the JavaScript
specification. In particular, since the value of the property can change as a consequence of
navigation, it is required that the property be configurable. (However, see tc39/ecma262 issue #672 and references to it
elsewhere in this specification for cases where we are not able to preserve these invariants, for
compatibility with existing web content.) [JAVASCRIPT] 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. Let desc be ? O.[[GetOwnProperty]](P). Assert: desc is not undefined. If IsDataDescriptor(desc) is true, then return
desc.[[Value]]. Assert: IsAccessorDescriptor(desc) is true. Let getter be desc.[[Get]]. If getter is undefined, then throw a " Let desc be ? O.[[GetOwnProperty]](P). Assert: desc is not undefined. If desc.[[Set]] is present and its value is not undefined, then:
Perform ? Call(setter, Receiver,
«V»). Return true. Throw a " Let keys be a new empty List. For each e of CrossOriginProperties(O), append e.[[Property]] to keys. Return the concatenation of keys and « " This abstract operation does not return a Completion Record. Support in all current engines. Support in all current engines. Support in all current engines. Support in all current engines. These attributes all return window. Support in all current engines. Returns the Support in all current engines. Returns the The A A The The The The If this's browsing context is null,
then return null. Return this's browsing context's
Support in all current engines. For historical reasons, Support in all current engines. Opens a window to show url (defaults to " These behave equivalently to the Encourages user agents to provide a minimal web browser user interface for the new
window. (Impacts the Support in all current engines. Returns the name of the window. Can be set, to change the name. Support in all current engines. Closes the window. Support in all current engines. Returns true if the window has been closed, false otherwise. 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 sourceDocument be the entry global object's associated If target is the empty string, then set target to " Let tokenizedFeatures be the result of tokenizing features. Let noopener and noreferrer be false. If tokenizedFeatures[" Set noopener to the result of parsing
tokenizedFeatures[" Remove tokenizedFeatures[" If tokenizedFeatures[" Set noreferrer to the result of parsing
tokenizedFeatures[" Remove tokenizedFeatures[" Let referrerPolicy be the empty string. If noreferrer is true, then set noopener to true and set
referrerPolicy to " Let targetNavigable and windowType be the result of applying the
rules for choosing a navigable given target, sourceDocument's
node navigable, 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 If targetNavigable is null, then return null. If windowType is either " Set targetNavigable's active browsing context's
is popup to the result of checking if a
popup window is requested, given tokenizedFeatures. Set up browsing context features for targetNavigable's active browsing context given
tokenizedFeatures.[CSSOMVIEW] Let urlRecord be the URL record
If url is not the empty string, then set urlRecord to the result
of encoding-parsing a URL given url, relative to the entry
settings object. If urlRecord is failure, then throw a " This is necessary in case url is something like Otherwise, navigate targetNavigable
to urlRecord using sourceDocument, with referrerPolicy set to referrerPolicy and
exceptionsEnabled set to true. Otherwise: If url is not the empty string, then: Let urlRecord be the result of encoding-parsing a URL
url, relative to the entry settings object. If urlRecord is failure, then throw a
" If noopener is false, then set targetNavigable's active browsing context's opener browsing context to
sourceDocument's browsing
context. If noopener is true or windowType is " Return targetNavigable's active
The The method provides a mechanism for navigating an
existing browsing context or opening and navigating an auxiliary browsing
context. 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[" Let location be the result of checking if
a window feature is set, given tokenizedFeatures, " Let toolbar be the result of checking if
a window feature is set, given tokenizedFeatures, " 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, If menubar is false, then return true. Let resizable be the result of checking if
a window feature is set, given tokenizedFeatures, " If resizable is false, then return true. Let scrollbars be the result of checking
if a window feature is set, given tokenizedFeatures, " If scrollbars is false, then return true. Let status be the result of checking if
a window feature is set, given tokenizedFeatures, " 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: To parse a boolean feature given
a string value: If value is the empty string, then return true. If value is " If value is " 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 Return this's navigable's target name. The Set this's navigable's active session history entry's document state's navigable target name to the given value. The name gets reset when the navigable is navigated to another origin. The Let thisTraversable be null. For each top-level traversable
traversable of the user agent's top-level traversable set: if
traversable's active document's relevant
global object equals this, then set thisTraversable to
traversable and break. If thisTraversable is null, then return. In this case the method is being called on a If thisTraversable's is closing is true, then return. Let browsingContext be thisTraversable's active browsing context. Let sourceSnapshotParams be the result of snapshotting source snapshot
params given thisTraversable's active
document. If all the following are true: then: Set thisTraversable's is closing to true. Queue a task on the DOM manipulation task source to close thisTraversable. A navigable is script-closable if its active
browsing context 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 traversable
whose session history entries's size is 1. The The Support in all current engines. Returns the number of document-tree child navigables. Returns the The Indexed access to document-tree child navigables is defined through
the [[GetOwnProperty]] internal method of the
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 The document-tree child
navigable target name property set of a Let children be the document-tree child navigables of
window's associated
Let firstNamedChildren be an empty ordered
set. For each navigable of children: Let name be navigable's target name. If name is the empty string, then continue. If firstNamedChildren contains a
navigable whose target name is name,
then continue. Append navigable to
firstNamedChildren. Let names be an empty ordered set. For each navigable of
firstNamedChildren: Let name be navigable's target name. If navigable's active document's origin is same origin with
window's relevant settings object's origin, then append name to names. Return names. The two seperate iterations mean that in the following example, hosted on The window's document-tree child navigable target name property
set; the value of the the value of the To determine the value of a named property
name in a Let objects be the list of named
objects of window with the name name. There will be at least one such object, since the algorithm would otherwise not
have been invoked by Web IDL. If objects contains a navigable, then: Let container be the first navigable container in
window's associated
Return container's content navigable's active Otherwise, if objects has only one element, return that element. Otherwise return an Named objects of document-tree child navigables of window's associated HTML elements that have an Since the Support in all current engines. Returns the Support in all current engines. Returns the Returns null if there isn't one or if it has been set to null. Can be set to null. Support in all current engines. Returns the Support in all current engines. Returns the navigable container element. Returns null if there isn't one, and in cross-origin situations. The Return this's navigable's top-level traversable's active
The Let current be this's browsing
context. If current is null, then return null. If current's opener browsing context is null, then return
null. Return current's opener browsing context's
The If the given value is null and this's browsing
context is non-null, then set this's browsing
context's opener browsing context to null. If the given value is non-null, then perform ?
DefinePropertyOrThrow(this, " Setting By default, scripts can access their opener browsing context's
The If navigable is null, then return null. If navigable's parent is not null, then set
navigable to navigable's parent. Return navigable's active
The Let current be this's node navigable. If current is null, then return null. Let container be current's container. If container is null, then return null. If container's node document's origin is not same origin-domain with the
current settings object's origin, then return null. Return container. An example of when these properties can return null is as follows: Here the browsing context corresponding to For historical reasons, the For privacy and interoperability reasons, those properties now return values that
represent whether the Each interface element is represented by a Support in all current engines. Support in all current engines. Support in all current engines. Support in all current engines. Support in all current engines. Support in all current engines. Support in all current engines. Returns true if the Support in all current engines. The 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 The The The The The The For historical reasons, the To 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
Return the current base URL of window's
associated Return the origin of window's
associated Return the policy container of
window's associated
Return true if both of the following hold, and false otherwise: realm's agent cluster's cross-origin-isolation mode is " window's associated
Return window's associated
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. A The There is no Every Although 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 children be the document-tree child navigables of
W's associated
Let value be undefined. If index is less than children's size, then: Sort children in ascending order, with
navigableA being less than navigableB if navigableA's container was inserted into W's associated Set value to children[index]'s active If value is undefined, then: 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 navigable target name property set, then: Let value be the active
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 " 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 " Let W be the value of the [[Window]] internal slot of this. Let maxProperties be W's associated Let keys be the range 0 to
maxProperties, exclusive. If IsPlatformObjectSameOrigin(W) is true, then return the
concatenation of keys and
OrdinaryOwnPropertyKeys(W). Return the concatenation of keys and !
CrossOriginOwnPropertyKeys(W). Support in all current engines. Support in all current engines. Support in all current engines. Each The To create a Let location be a new Let valueOf be location's relevant
realm.[[Intrinsics]].[[%Object.prototype.valueOf%]]. Perform ! location.[[DefineOwnProperty]](" Perform ! location.[[DefineOwnProperty]](@@toPrimitive, {
[[Value]]: undefined,
[[Writable]]: false,
[[Enumerable]]: false,
[[Configurable]]: false }). Set the value of the [[DefaultProperties]] internal slot of
location to location.[[OwnPropertyKeys]](). Return location. The addition of Returns a Can be set, to navigate to another page. The The Support in all current engines. Support in all current engines. Returns the Can be set, to navigate to the given URL. Support in all current engines. Returns the Support in all current engines. Returns the Can be set, to navigate to the same URL with a changed scheme. Support in all current engines. Returns the Can be set, to navigate to the same URL with a changed host and port. Support in all current engines. Returns the Can be set, to navigate to the same URL with a changed host. Support in all current engines. Returns the Can be set, to navigate to the same URL with a changed port. Support in all current engines. Returns the Can be set, to navigate to the same URL with a changed path. Support in all current engines. Returns the Can be set, to navigate to the same URL with a changed query (ignores leading " Support in all current engines. Returns the Can be set, to navigate to the same URL with a changed fragment (ignores leading " Support in all current engines. Navigates to the given URL. Support in all current engines. Removes the current page from the session history and navigates to the given URL. Support in all current engines. Reloads the current page. Returns a A A A Let output be a new list of strings. Let current be the While current's container document
is non-null: Set current to current's container document. Append the serialization of current's origin to output. Return output. To Let navigable be location's relevant global object's
navigable. Let sourceDocument be the incumbent
global object's associated
If location's relevant Navigate navigable to url using
sourceDocument, with exceptionsEnabled set to true and historyHandling set to historyHandling. The If this's relevant The If this's relevant Let url be the result of encoding-parsing a URL given the given
value, relative to the entry settings object. If url is failure, then throw a " The The If this's relevant The If this's relevant The If this's relevant If this's relevant Let possibleFailure be the result of basic URL
parsing the given value, followed by " Because the URL parser ignores multiple consecutive colons, providing a value
of " If possibleFailure is failure, then throw a
" The If this's relevant If url's host is null, return the empty
string. If url's port is null, return
url's host, serialized. Return url's host, serialized, followed by " The If this's relevant If this's relevant If copyURL has an opaque path, then return. Basic URL parse the given value, with
copyURL as url and host
state as state
override. The If this's relevant Return this's url's host, serialized. The If this's relevant If this's relevant If copyURL has an opaque path, then return. Basic URL parse the given value, with
copyURL as url and hostname
state as state
override. The If this's relevant Return this's url's port, serialized. The If this's relevant If this's relevant If copyURL cannot have a username/password/port, then
return. If the given value is the empty string, then set copyURL's port to null. Otherwise, basic URL parse the given value, with
copyURL as url and port
state as state
override. The If this's relevant The If this's relevant If this's relevant If copyURL has an opaque path, then return. Set copyURL's path to the empty
list. Basic URL parse the given value, with
copyURL as url and path start
state as state
override. The If this's relevant The If this's relevant If this's relevant If the given value is the empty string, set copyURL's query to null.
Otherwise, run these substeps: Let input be the given value with a single leading " Set copyURL's query to the empty
string. Basic URL parse input, with null, the
relevant The If this's relevant The If this's relevant If this's relevant Let input be the given value with a single leading " Set copyURL's fragment to the empty
string. Basic URL parse input, with
copyURL as url and fragment
state as state
override. If copyURL's fragment is
this's url's fragment, then return. This bailout is necessary for compatibility with deployed content, which redundantly sets Unlike the equivalent API for the The If this's relevant If this's relevant If urlRecord is failure, then throw a " The If this's relevant Let urlRecord be the result of encoding-parsing a URL given
url, relative to the entry settings object. If urlRecord is failure, then throw a " The The Let document be this's relevant
If document is null, then return. If document's origin is not
same origin-domain with the entry settings object's origin, then throw a
" The If this's relevant If this's relevant The details of how the As explained earlier, the Also, every If IsPlatformObjectSameOrigin(this) is true, then return !
OrdinaryGetPrototypeOf(this). Return null. Return ! SetImmutablePrototype(this, V). Return true. Return false. If IsPlatformObjectSameOrigin(this) is true, then: Let desc be OrdinaryGetOwnProperty(this,
P). If the value of the [[DefaultProperties]] internal slot of this
contains P, then set desc.[[Configurable]] to true. Return desc. Let property be CrossOriginGetOwnPropertyHelper(this,
P). If property is not undefined, then return property. Return ? CrossOriginPropertyFallback(P). If IsPlatformObjectSameOrigin(this) is true, then: If the value of the [[DefaultProperties]] internal slot of this
contains P, then return false. Return ? OrdinaryDefineOwnProperty(this, P,
Desc). Throw a " If IsPlatformObjectSameOrigin(this) is true, then return ?
OrdinaryGet(this, P, Receiver). Return ? CrossOriginGet(this, P,
Receiver). If IsPlatformObjectSameOrigin(this) is true, then return ?
OrdinarySet(this, P, V, Receiver). Return ? CrossOriginSet(this, P, V,
Receiver). If IsPlatformObjectSameOrigin(this) is true, then return ?
OrdinaryDelete(this, P). Throw a " If IsPlatformObjectSameOrigin(this) is true, then return
OrdinaryOwnPropertyKeys(this). Return CrossOriginOwnPropertyKeys(this). Support in all current engines. Support in all current engines. Support in all current engines. Returns the number of overall session history
entries for the current traversable navigable. Support in all current engines. Returns the scroll restoration mode of
the active session history entry. Set the scroll restoration mode of the
active session history entry to
value. Support in all current engines. Returns the classic history API state
of the active session history entry, deserialized
into a JavaScript value. Reloads the current page. Support in all current engines. Goes back or forward the specified number of steps in the overall session history entries list for the current
traversable navigable. A zero delta will reload the current page. If the delta is out of range, does nothing. Support in all current engines. Goes back one step in the overall session history
entries list for the current traversable navigable. If there is no previous page, does nothing. Support in all current engines. Goes forward one step in the overall session
history entries list for the current traversable navigable. If there is no next page, does nothing. Support in all current engines. Adds a new entry into session history with its classic history API state set to a serialization
of data. The active history entry's
URL will be copied over and used for the new entry's URL. (The second parameter exists for historical reasons, and cannot be omitted; passing the
empty string is traditional.) Adds a new entry into session history with its classic history API state set to a serialization
of data, and with its URL set to url. If the current (The second parameter exists for historical reasons, and cannot be omitted; passing the
empty string is traditional.) Support in all current engines. Updates the classic history API state of
the active session history entry to a structured
clone of data. (The second parameter exists for historical reasons, and cannot be omitted; passing the
empty string is traditional.) Updates the classic history API state of
the active session history entry to a structured
clone of data, and its URL to url. If the current (The second parameter exists for historical reasons, and cannot be omitted; passing the
empty string is traditional.) A The Each Each Each Although the index is not directly
exposed, it can be inferred from changes to the length during synchronous navigations. In fact, that is
what it's used for. The If this's relevant global object's associated The If this's relevant global object's associated The If this's relevant global object's associated The If this's relevant global object's associated The The The To delta traverse a Let document be history's relevant global object's
associated If document is not fully active, then throw a
" Traverse the history by a delta given document's node
navigable's traversable navigable, delta,
and with sourceDocument set to
document. The The The shared history push/replace state steps, given a Let document be history's associated If document is not fully active, then throw a
" Let serializedData be
StructuredSerializeForStorage(data). Rethrow any exceptions. Let newURL be document's URL. If url is not null or the empty string, then: Set newURL to the result of encoding-parsing a URL given
url, relative to the relevant settings object of
history. If newURL is failure, then throw a " Let navigation be history's relevant global object's
navigation API. Let continue be the result of firing a push/replace/reload If continue is false, then return. Run the URL and history update steps given document and
newURL, with serializedData set to
serializedData and historyHandling set to
historyHandling. User agents may limit the number of state objects added to the session history per page. If a
page hits the implementation-defined limit, user agents must remove the entry
immediately after the first entry for that A Let documentURL be document's URL. If targetURL and documentURL differ in their scheme, username,
password, host, or port
components, then return false. If targetURL's scheme is an
HTTP(S) scheme, then return true. (Differences in path, query, and fragment are allowed for If targetURL's scheme is " If targetURL and documentURL differ in their path component or query
components, then return false. (Only differences in fragment are allowed for other types of URLs.) Return true. Note how only the URL of the Consider a game where the user can navigate along a line, such that the user is always at some
coordinate, and such that the user can bookmark the page corresponding to a particular
coordinate, to return to it later. A static page implementing the x=5 position in such a game could look like the following: The problem with such a system is that each time the user clicks, the whole page has to be
reloaded. Here instead is another way of doing it, using script: In systems without script, this still works like the previous example. However, users that
do have script support can now navigate much faster, since there is no network access
for the same experience. Furthermore, contrary to the experience the user would have with just a
naïve script-based approach, bookmarking and navigating the session history still work. In the example above, the data argument to the Most applications want to use the same scroll restoration mode value for all of
their history entries. To achieve this they can set the This section is non-normative. The navigation API, provided by the global One ability the API provides is inspecting session history entries. For example, the following will display the entries' URLs in an ordered list: The The navigation API can also be used to navigate, reload, or traverse through the history: Note that traversals are again limited to same-origin destinations, meaning that, for example, The most powerful part of the navigation API is the (The event will not fire for location bar-initiated navigations, or navigations initiated from other windows, when the destination of the navigation is a new document.) Much of the time, the event's The The Note that the Each The The following are the event handlers (and their corresponding event handler event types) that must be supported,
as event handler IDL attributes, by all objects implementing the
Each Each The current entry of a If navigation has entries and events disabled, then return
null. Assert: navigation's current entry index is not −1. Return navigation's entry
list[navigation's current entry
index]. A Let document be navigation's relevant global object's
associated If document is not fully active, then return true. If document's is initial Return false. To get the navigation API entry
index of a session history entry she within a
Let index be 0. For each nhe of navigation's entry list: If nhe's session history entry is equal to
she, then return index. Increment index by 1. Return −1. A key type used throughout the navigation API is the This captures the main web developer-visible types of "navigations", which (as noted elsewhere) do not exactly correspond to this standard's
singular navigate algorithm. The meaning of each value is the following: The value space of the To initialize the navigation API entries for a new document given a
Assert: navigation's entry
list is empty. Assert: navigation's current entry index is −1. If navigation has entries and events disabled, then
return. For each newSHE of newSHEs: Let newNHE be a new Set newNHE's session history entry to
newSHE. Append newNHE to navigation's
entry list. newSHEs will have originally come from getting session history
entries for the navigation API, and thus each newSHE will be contiguous same origin with
initialSHE. Set navigation's current entry
index to the result of getting the navigation API entry index of
initialSHE within navigation. To update the navigation API entries for reactivation given a
If navigation has entries and events disabled, then
return. Let newNHEs be a new empty list. Let oldNHEs be a clone of
navigation's entry list. For each newSHE of newSHEs: Let newNHE be null. If oldNHEs contains a
Set newNHE to matchingOldNHE. Remove matchingOldNHE from
oldNHEs. Otherwise: Set newNHE to a new Set newNHE's session history entry to
newSHE. Append newNHE to
newNHEs. newSHEs will have originally come from getting session history
entries for the navigation API, and thus each newSHE will be contiguous same origin with
reactivatedSHE. By the end of this loop, all Set navigation's entry list to newNHEs. Set navigation's current entry
index to the result of getting the navigation API entry index of
reactivatedSHE within navigation. Queue a global task on the navigation and traversal task source
given navigation's relevant global object to run the following
steps: For each disposedNHE of
oldNHEs: Fire an event named We delay these steps by a task to ensure that (However, the rest of this algorithm runs before the To update the navigation API entries for a same-document navigation given a
If navigation has entries and events disabled, then
return. Let oldCurrentNHE be the current
entry of navigation. Let disposedNHEs be a new empty list. If navigationType is " Set navigation's current entry
index to the result of getting the navigation API entry index of
destinationSHE within navigation. Assert: navigation's current entry index is not −1. This algorithm is only called for same-document traversals. Cross-document
traversals will instead call either initialize the navigation API entries for a new
document or update the navigation API entries for reactivation. Otherwise, if navigationType is " Set navigation's current entry
index to navigation's current
entry index + 1. Let i be navigation's current entry index. While i < navigation's entry list's size: Append navigation's entry list[i] to
disposedNHEs. Set i to i + 1. Remove all items in disposedNHEs from
navigation's entry list. Otherwise, if navigationType is " Append oldCurrentNHE to
disposedNHEs. If navigationType is " Let newNHE be a new Set newNHE's session history entry to
destinationSHE. Set navigation's entry
list[navigation's current entry
index] to newNHE. If navigation's ongoing API method tracker is non-null, then
notify about the committed-to entry given navigation's ongoing API
method tracker and the current entry of
navigation. It is important to do this before firing the Prepare to run script given navigation's relevant settings
object. See the discussion
for other navigation API events to understand why we do this. Fire an event named For each disposedNHE of
disposedNHEs: Fire an event named Clean up after running script given navigation's relevant
settings object. In implementations, same-document navigations can cause session history entries to be disposed by falling off the back of the
session history entry list. This is not yet handled by the above algorithm (or by any other part
of this standard). See issue #8620 to
track progress on defining the correct behavior in such cases. The URL of this navigation history entry. This can return null if the entry corresponds to a different A user agent-generated random UUID string representing this navigation history entry's place
in the navigation history list. This value will be reused by other
This is useful for navigating back to this entry in the navigation history list, using A user agent-generated random UUID string representing this specific navigation history
entry. This value will not be reused by other This is useful for associating data with this navigation history entry using other storage
APIs. The index of this Indicates whether or not this navigation history entry is for the same
Returns the deserialization of the state stored
in this entry, which was added to the entry using Note that in general, unless the state value is a primitive, This state is unrelated to the classic history API's Each The key of a
If nhe's relevant global object's associated Return nhe's session history entry's navigation API key. The ID of a
If nhe's relevant global object's associated Return nhe's session history entry's navigation API ID. The index of a
If nhe's relevant global object's associated Return the result of getting the navigation API entry index of
this's session history entry within
this's relevant global object's navigation API. The Let document be this's relevant global object's associated If document is not fully active, then return the empty
string. Let she be this's session history
entry. If she's document does not equal
document, and she's document
state's request referrer
policy is " Return she's URL, serialized. The The The The Let document be this's relevant global object's associated If document is not fully active, then return false. Return true if this's session history entry's
document equals document, and false
otherwise. The If this's relevant global object's associated Return StructuredDeserialize(this's session
history entry's navigation API state).
Rethrow any exceptions. This can in theory throw an exception, if attempting to deserialize a large
The following are the event handlers (and their corresponding event handler event types) that must be supported,
as event handler IDL attributes, by all objects implementing the
Returns an array of Returns the Updates the navigation API state of the current session history entry, without performing a
navigation like This method is best used to capture updates to the page that have already happened, and need
to be reflected into the navigation API state. For cases where the state update is meant to
drive a page update, instead use Returns true if the current current session
history entry (i.e., Returns true if the current current session
history entry (i.e., The If this has entries and events disabled, then return the empty
list. Return this's entry list. Recall that because of Web IDL's sequence type conversion rules, this will
create a new JavaScript array object on each call. That is, The The Let current be the current entry
of this. If current is null, then throw an " Set current's session history entry's navigation API state to
serializedState. Fire an event named The If this has entries and events disabled, then return
false. Assert: this's current entry index is not −1. If this's current entry
index is 0, then return false. Return true. The If this has entries and events disabled, then return
false. Assert: this's current entry index is not −1. If this's current entry
index is equal to this's entry
list's size, then return false. Return true. Navigates the current page to the given url.
options can contain the following values: By default this will perform a full navigation (i.e., a cross-document navigation, unless the
given URL differs only in a fragment from the current
one). The The returned promises will behave as follows: For navigations that get aborted, both promises will reject with an
" For other same-document navigations (e.g., non-intercepted fragment navigations), both promises will fulfill
immediately. For cross-document navigations, or navigations that result in 204 or 205 statuses or ` In all cases, when the returned promises fulfill, it will be with the
Reloads the current page. options can contain The default behavior of performing a from-network-or-cache reload of the current page can be
overriden by the using the The returned promises will behave as follows: If the reload is intercepted by using the Otherwise, both promises will never settle. Traverses to the closest session
history entry that matches the If a traversal to that session history entry is already in progress, then this
will return the promises for that original traversal, and The returned promises will behave as follows: If there is no For non-intercepted same-document travesals, both promises will fulfill as soon as the
traversal is processed and For cross-document traversals, including attempted cross-document traversals that end up
resulting in a 204 or 205 statuses or ` Traverses to the closest previous session history entry which results in this
navigable traversing, i.e., which corresponds to a different
If a traversal to that session history entry is already in progress, then this
will return the promises for that original traversal, and The returned promises behave equivalently to those returned by Traverses to the closest forward session history entry which results in this
navigable traversing, i.e., which corresponds to a different
If a traversal to that session history entry is already in progress, then this
will return the promises for that original traversal, and The returned promises behave equivalently to those returned by The Let urlRecord be the result of encoding-parsing a URL given
url, relative to this's relevant settings object. If urlRecord is failure, then return an early error result for a
" If options[" Let state be options[" Let serializedState be
StructuredSerializeForStorage(state). If this throws an exception, then
return an early error result for that
exception. It is importantly to perform this step early, since serialization can invoke web
developer code, which in turn might change various things we check in later steps. If document is not fully active, then return an early error result for an
" If document's unload counter is greater than 0, then return an
early error result for an
" Let apiMethodTracker be the result of maybe setting the upcoming non-traverse API method
tracker for this given info and
serializedState. Navigate document's node
navigable to urlRecord using document, with historyHandling set to options[" Unlike If this's upcoming non-traverse API method tracker is
apiMethodTracker, then: If the upcoming non-traverse API method tracker is still
apiMethodTracker, this means that the navigate algorithm bailed out
before ever getting to the inner Set this's upcoming non-traverse API method tracker to
null. Return an early error result for
an " Return a navigation API method tracker-derived result for
apiMethodTracker. The Let document be this's relevant global object's associated Let serializedState be
StructuredSerializeForStorage(undefined). If options[" It is importantly to perform this step early, since serialization can invoke web
developer code, which in turn might change various things we check in later steps. Otherwise: Let current be the current
entry of this. If current is not null, then set serializedState to
current's session history entry's navigation API state. If document is not fully active, then return an early error result for an
" If document's unload counter is greater than 0, then return an
early error result for an
" Let apiMethodTracker be the result of maybe setting the upcoming non-traverse API method
tracker for this given info and
serializedState. Reload document's node navigable with navigationAPIState set to
serializedState. Return a navigation API method tracker-derived result for
apiMethodTracker. The If this's current entry
index is −1, then return an early
error result for an " The If this's current entry
index is −1 or 0, then return an early error result for an
" Return the result of performing a navigation API traversal given
this, key, and options. The If this's current entry
index is −1 or is equal to this's entry list's size −
1, then return an early error result for
an " Return the result of performing a navigation API traversal given
this, key, and options. To perform a navigation API traversal
given a Let document be navigation's relevant global object's
associated If document is not fully active, then return an early error result for an
" If document's unload counter is greater than 0, then return an
early error result for an
" If key equals current's session history
entry's navigation API key, then return «[
" If navigation's upcoming traverse API method
trackers[key] exists, then return a
navigation API method tracker-derived result for navigation's
upcoming traverse API method trackers[key]. Let info be options[" Let apiMethodTracker be the result of adding an upcoming traverse API method tracker for
navigation given key and info. Let navigable be document's node navigable. Let traversable be navigable's traversable navigable. Let sourceSnapshotParams be the result of snapshotting source snapshot
params given document. Append the following session history
traversal steps to traversable: Let navigableSHEs be the result of getting session history
entries given navigable. Let targetSHE be the session history entry in
navigableSHEs whose navigation API key
is key. If no such entry exists, then: Queue a global task on the navigation and traversal task
source given navigation's relevant global object to
reject the finished promise for apiMethodTracker with an
" This path is taken if navigation's entry list was outdated compared to
navigableSHEs, which can occur for brief periods while all the relevant threads and
processes are being synchronized in reaction to a history change. If targetSHE is navigable's active session history entry, then abort these
steps. This can occur if a previously queued traversal already took us to
this session history entry. In that case the previous traversal will have dealt
with apiMethodTracker already. Let result be the result of applying the traverse history step given by targetSHE's step to traversable, given sourceSnapshotParams,
navigable, and " If result is " If result is " When result is " In the " Return a navigation API method tracker-derived result for
apiMethodTracker. An early error result for an exception
e is a A navigation API method tracker-derived result for a navigation API method
tracker is a During any given navigation (in the broad sense of the
word), the We also cannot assume there is only a single navigation requested at any given time, due to web
developer code such as: That is, in this scenario, we need to ensure that while navigating to We end up accomplishing all this by associating the following with each
Ongoing Focus changed during ongoing navigation, a boolean, initially false. Suppress normal scroll restoration during ongoing navigation, a boolean,
initially false. Ongoing API method tracker, a navigation API method tracker or
null, initially null. Upcoming non-traverse API method tracker, a navigation API method
tracker or null, initially null. Upcoming traverse API method trackers, a map from strings to navigation API method trackers, initially
empty. The state here that is not stored in navigation API method trackers is state which needs to be tracked even for
navigations that are not initiated via navigation API methods. A navigation API method tracker is a struct with the following items: A navigation object, a
A key, a string or null An info, a JavaScript
value A serialized state, a
serialized state or null A committed-to entry,
a A committed promise, a
promise A finished promise, a
promise All this state is then managed via the following algorithms. To maybe set the upcoming non-traverse API method tracker given a
Let committedPromise and finishedPromise be new promises created in
navigation's relevant realm. Mark as handled finishedPromise. Let apiMethodTracker be a new navigation API method tracker with: Assert: navigation's upcoming non-traverse API method
tracker is null. If navigation does not have
entries and events disabled, then set navigation's upcoming
non-traverse API method tracker to apiMethodTracker. If navigation has entries and events disabled, then
committedPromise and finishedPromise will never fulfill (since we never
create a Return apiMethodTracker. To add an upcoming traverse API method tracker given a Let committedPromise and finishedPromise be new promises created in
navigation's relevant realm. Mark as handled finishedPromise. See the previous
discussion about why this is done. Let apiMethodTracker be a new navigation API method tracker with: Set navigation's upcoming traverse API method
trackers[key] to apiMethodTracker. Return apiMethodTracker. To promote an upcoming API method tracker to ongoing given a Assert: navigation's ongoing API method tracker is
null. If destinationKey is not null, then: Assert: navigation's upcoming non-traverse API method
tracker is null. If navigation's upcoming traverse API method
trackers[destinationKey] exists, then: Set navigation's ongoing API method tracker to
navigation's upcoming traverse API method
trackers[destinationKey]. Remove navigation's upcoming
traverse API method trackers[destinationKey]. Otherwise: Set navigation's ongoing API method tracker to
navigation's upcoming non-traverse API method tracker. Set navigation's upcoming non-traverse API method tracker to
null. To clean up a navigation API
method tracker apiMethodTracker: Let navigation be apiMethodTracker's navigation object. If navigation's ongoing API method tracker is
apiMethodTracker, then set navigation's ongoing API method
tracker to null. Otherwise: Let key be apiMethodTracker's key. Assert: key is not null. Assert: navigation's upcoming traverse API method
trackers[key] exists. Remove navigation's upcoming traverse
API method trackers[key]. To notify about the committed-to entry given a navigation API method
tracker apiMethodTracker and a Set apiMethodTracker's committed-to entry to
nhe. If apiMethodTracker's serialized state is not null, then set
nhe's session history entry's navigation API state to apiMethodTracker's
serialized state. If it's null, then we're traversing to nhe via At this point, apiMethodTracker's serialized state is no longer needed.
Implementations might want to clear it out to avoid keeping it alive for the lifetime of the
navigation API method tracker. Resolve apiMethodTracker's committed promise with
nhe. At this point, apiMethodTracker's committed promise is only needed in
cases where it has not yet been returned to author code. Implementations might want to clear it
out to avoid keeping it alive for the lifetime of the navigation API method
tracker. To resolve the finished promise for a navigation API method tracker
apiMethodTracker: Resolve apiMethodTracker's committed promise with its committed-to entry. Usually, notify about the committed-to entry has previously been
called on apiMethodTracker, and so this will do nothing. However, in some cases
resolve the finished promise is called directly, in which case this step is
necessary. Resolve apiMethodTracker's finished promise with its committed-to entry. Clean up
apiMethodTracker. To reject the finished promise for a navigation API method tracker
apiMethodTracker with a JavaScript value exception: Reject apiMethodTracker's committed promise with
exception. This will do nothing if apiMethodTracker's committed promise was previously
resolved via notify about the committed-to entry. Reject apiMethodTracker's finished promise with
exception. Clean up
apiMethodTracker. To abort the ongoing navigation given a Let event be navigation's ongoing Assert: event is not null. Set navigation's focus changed during ongoing navigation to
false. Set navigation's suppress normal scroll restoration during ongoing
navigation to false. If error was not given, then let error be a new
" If event's dispatch flag is set, then set event's
canceled flag to true. Signal abort on event's abort controller given
error. Set navigation's ongoing Fire an event named Thus, for example, if this algorithm is reached because of a call to If navigation's ongoing API method tracker is non-null, then
reject the finished promise for apiMethodTracker with
error. If navigation's transition is
not null, then: Reject navigation's transition's finished promise with
error. Set navigation's transition to null. To inform the navigation API about aborting navigation in a navigable
navigable: If this algorithm is running on navigable's active
window's relevant agent's event
loop, then continue on to the following steps. Otherwise, queue a global task
on the navigation and traversal task source given navigable's active window to run the following steps. Let navigation be navigable's active
window's navigation API. If navigation's ongoing Abort the ongoing navigation given navigation. To inform the navigation API about child navigable destruction given a
navigable navigable: Inform the navigation API about aborting navigation in
navigable. Let navigation be navigable's active
window's navigation API. Let traversalAPIMethodTrackers to be clone of
navigation's upcoming traverse API method trackers. For each apiMethodTracker of
traversalAPIMethodTrackers: reject the finished promise for
apiMethodTracker with a new " The ongoing navigation concept is most-directly exposed to web developers through the A Since One of " The A promise which fulfills at the same time as the Each The Each Each Each The The The A major feature of the navigation API is the One of " A True if Generally speaking, this will be true whenever the current True if this navigation was due to a user clicking on an True for a fragment navigation; false
otherwise. An The expected pattern is for developers to pass this along to any async operations, such as
The (Notably, this will be null even for " Represents whether or not this navigation was requested to be a download, by using an
If a download was not requested, then this property is null. If a download was requested, returns the filename that was supplied as the Note that a download being requested does not always mean that a download will happen: for
example, a download might be blocked by browser security policies, or end up being treated as a
" Similarly, a navigation might end up being a download even if it was not requested to be one,
due to the destination server responding with a ` Finally, note that the An arbitrary JavaScript value passed via one of the navigation API methods which initiated this
navigation, or undefined if the navigation was initiated by the user or by a different
API. Returns true if the user agent performed a visual transition for this navigation before
dispatching this event. If true, the best user experience will be given if the author
synchronously updates the DOM to the post-navigation state. Intercepts this navigation, preventing its normal handling and instead converting it into a
same-document navigation of the same type to the destination URL. The By default, using this method will cause focus to reset when any handlers' returned promises
settle. Focus will be reset to the first element with the By default, using this method will delay the browser's scroll restoration logic for " This method will throw a " For " For " If called more than once, or called after automatic post-transition scroll processing has
happened due to the Each Each Each Each Each Each The The Perform shared checks given
this. If this's Set this's interception state to " If options[" If options[" If this's focus reset
behavior is not null, and it is not equal to options[" Set this's focus reset
behavior to options[" If options[" If this's scroll
behavior is not null, and it is not equal to options[" Set this's scroll
behavior to options[" The Perform shared checks given
this. If this's interception state is not " To perform shared checks for a
If event's relevant global object's associated The URL being navigated to. The value of the The value of the The value of the Indicates whether or not this navigation is to the same Note that this property indicates the original nature of the navigation. If a cross-document
navigation is converted into a same-document navigation using For " For " For " Each Each It will be non-null if and only if the Each Each The The The The The The Other parts of the standard fire the To fire a traverse Let event be the result of creating an event given
Set event's classic history API state to
null. Let destination be a new Let destinationNHE be the If destinationNHE is non-null, then: Set destination's entry to
destinationNHE. Set destination's state to destinationSHE's navigation API state. Otherwise, Set destination's entry to null. Set destination's state to
StructuredSerializeForStorage(null). Set destination's is
same document to true if destinationSHE's document is equal to navigation's relevant global
object's associated Return the result of performing the inner To fire a push/replace/reload Let event be the result of creating an event given
Set event's classic history API state to
classicHistoryAPIState. Let destination be a new Set destination's URL
to destinationURL. Set destination's entry to null. Set destination's state to
navigationAPIState. Set destination's is
same document to isSameDocument. Return the result of performing the inner To fire a download request Let event be the result of creating an event given
Set event's classic history API state to
null. Let destination be a new Set destination's URL
to destinationURL. Set destination's entry to null. Set destination's state to
StructuredSerializeForStorage(null). Set destination's is
same document to false. Return the result of performing the inner The inner If navigation has entries and events disabled, then: Assert: navigation's ongoing API method tracker is
null. Assert: navigation's upcoming non-traverse API method
tracker is null. Assert: navigation's upcoming traverse API method
trackers is empty. Return true. These assertions holds because Let destinationKey be null. If destination's entry is non-null, then set
destinationKey to destination's entry's key. Assert: destinationKey is not the empty string. Promote an upcoming API method tracker to ongoing given
navigation and destinationKey. Let apiMethodTracker be navigation's ongoing API method
tracker. Let navigable be navigation's relevant global object's
navigable. Let document be navigation's relevant global object's
associated If document can have its URL rewritten to destination's
URL, and either destination's
is same document is true or
navigationType is not " If either: navigationType is not " traverseCanBeCanceled is true the initialize event's Initialize event's Initialize event's Initialize event's Initialize event's If apiMethodTracker is not null, then initialize event's At this point apiMethodTracker's info is no longer needed and can be nulled
out instead of keeping it alive for the lifetime of the navigation API method
tracker. Initialize event's Set event's abort
controller to a new Initialize event's Let currentURL be document's URL. If all of the following are true: destination's is
same document is true; destination's URL
equals currentURL with exclude fragments set to true; and destination's URL's
fragment is not identical to
currentURL's fragment, then initialize event's If userInvolvement is not " If formDataEntryList is not null, then initialize event's Assert: navigation's ongoing Set navigation's ongoing Set navigation's focus changed during ongoing navigation to
false. Set navigation's suppress normal scroll restoration during ongoing
navigation to false. Let dispatchResult be the result of dispatching event at
navigation. If dispatchResult is false: If navigationType is " If event's abort
controller's signal is not aborted, then abort the ongoing navigation
given navigation. Return false. Let endResultIsSameDocument be true if event's interception state is not " Prepare to run script given navigation's relevant settings
object. If event's interception
state is not " Set event's interception state to " Let fromNHE be the current
entry of navigation. Assert: fromNHE is not null. Set navigation's transition to a new
Mark as handled navigation's transition's finished promise. See the discussion
about other finished promises to understand why this is done. If navigationType is " If event's scroll
behavior was set to " If navigationType is " If navigationType is " If navigationType is " If endResultIsSameDocument is true: Let promisesList be an empty list. For each handler of event's navigation handler list: If promisesList's size is 0, then set
promisesList to « a promise resolved with undefined ». There is a subtle timing difference between how waiting for all schedules its success and failure steps when given zero promises
versus ≥1 promises. For most uses of waiting for all,
this does not matter. However, with this API, there are so many events and promise handlers
which could fire around the same time that the difference is pretty easily observable: it can
cause the event/promise handler sequence to vary. (Some of the events and promises involved
include: Wait for all of promisesList, with the following success steps: If event's relevant global object is not fully
active, then abort these steps. If event's abort
controller's signal is aborted, then abort these steps. Assert: event equals navigation's ongoing
Set navigation's ongoing Finish event given
true. Fire an event named If navigation's transition is not null, then resolve
navigation's transition's
finished promise with
undefined. Set navigation's transition to null. If apiMethodTracker is non-null, then resolve the finished
promise for apiMethodTracker. and the following failure steps given reason rejectionReason: If event's relevant global object is not fully
active, then abort these steps. If event's abort
controller's signal is aborted, then abort these steps. Assert: event equals navigation's ongoing
Set navigation's ongoing Finish event given
false. Fire an event named If navigation's transition is not null, then reject
navigation's transition's
finished promise with
rejectionReason. Set navigation's transition to null. If apiMethodTracker is non-null, then reject the finished
promise for apiMethodTracker with rejectionReason. Otherwise, if apiMethodTracker is non-null, then clean up
apiMethodTracker. Clean up after running script given navigation's relevant
settings object. Per the previous
note, this stops suppressing any potential promise handler microtasks, causing them to run
at this point or later. If event's interception
state is " Return false. By calling To finish a Assert: event's interception state is not " If event's interception
state is " Potentially reset the focus given event. If didFulfill is true, then potentially process scroll behavior
given event. Set event's interception state to " To potentially reset the focus given a Assert: event's interception state is " Let navigation be event's relevant global object's
navigation API. Let focusChanged be navigation's focus changed during ongoing
navigation. Set navigation's focus changed during ongoing navigation to
false. If focusChanged is true, then return. If event's focus reset
behavior is " If it was left as null, then we treat that as " Let document be event's relevant global object's associated Let focusTarget be the autofocus delegate for
document. If focusTarget is null, then set focusTarget to
document's body element. If focusTarget is null, then set focusTarget to
document's document element. Run the focusing steps for focusTarget, with document's
viewport as the fallback target. Move the sequential focus navigation starting point to
focusTarget. To potentially process scroll behavior given a Assert: event's interception state is " If event's interception
state is " If event's scroll behavior is
" If it was left as null, then we treat that as " Process scroll behavior given event. To process scroll behavior given a Assert: event's interception state is " Set event's interception state to " If event's Otherwise: Let document be event's relevant global object's
associated If document's indicated part is null, then scroll to the
beginning of the document given document. [CSSOMVIEW] Otherwise, scroll to the fragment given document. The Returns the type of navigation which caused the current entry to change, or null if the
change is due to Returns the previous value of If The Support in all current engines. Support in all current engines. Support in all current engines. Returns a copy of the information that was provided to Returns true if the user agent performed a visual transition for this navigation before
dispatching this event. If true, the best user experience will be given if the author
synchronously updates the DOM to the post-navigation state. The The HashChangeEvent/HashChangeEvent Support in all current engines. Support in all current engines. Support in all current engines. Returns the URL of the session history entry that was previously
current. Support in all current engines. Returns the URL of the session history entry that is now
current. The The PageTransitionEvent/PageTransitionEvent Support in all current engines. Support in all current engines. Support in all current engines. For the For the Things that can cause the page to be unsalvageable include: The To fire a page transition event named eventName at a The values for Support in all current engines. There are no The The This attribute is a SecurityError" 7.2.1.2 Shared internal slot: [[CrossOriginPropertyDescriptorMap]]
Window and Location objects both have a
[[CrossOriginPropertyDescriptorMap]] internal slot, whose value is initially an empty
map.Window or
Location object from objectGlobal. It is filled lazily by
CrossOriginGetOwnPropertyHelper, which consults it on future lookups.const href =
Object.getOwnPropertyDescriptor(crossOriginLocation, "href").set the value and its
corresponding key in the map cannot be garbage collected as that would be observable.document.domain is set. This is not observable as document.domain cannot revisit an earlier value.document.domain
to "example.com" on www.example.com means user agents can remove all
key-value pairs from the map where part of the key is www.example.com, as that can never be part
of the origin again and therefore the corresponding value could never be retrieved
from the map.7.2.1.3 Shared abstract operations
7.2.1.3.1 CrossOriginProperties ( O )
Location object, then return «
{ [[Property]]: "href", [[NeedsGet]]: false, [[NeedsSet]]: true },
{ [[Property]]: "replace" } ».window", [[NeedsGet]]: true, [[NeedsSet]]: false },
{ [[Property]]: "self", [[NeedsGet]]: true, [[NeedsSet]]: false },
{ [[Property]]: "location", [[NeedsGet]]: true, [[NeedsSet]]: true },
{ [[Property]]: "close" },
{ [[Property]]: "closed", [[NeedsGet]]: true, [[NeedsSet]]: false },
{ [[Property]]: "focus" },
{ [[Property]]: "blur" },
{ [[Property]]: "frames", [[NeedsGet]]: true, [[NeedsSet]]: false },
{ [[Property]]: "length", [[NeedsGet]]: true, [[NeedsSet]]: false },
{ [[Property]]: "top", [[NeedsGet]]: true, [[NeedsSet]]: false },
{ [[Property]]: "opener", [[NeedsGet]]: true, [[NeedsSet]]: false },
{ [[Property]]: "parent", [[NeedsGet]]: true, [[NeedsSet]]: false },
{ [[Property]]: "postMessage" } ».WindowProxy object.window", "self", "location", "close", "closed",
"focus", "blur", "frames",
"length", "top", "opener",
"parent", "postMessage", or an array index
property name.7.2.1.3.2 CrossOriginPropertyFallback ( P )
then", @@toStringTag,
@@hasInstance, or @@isConcatSpreadable, then return
PropertyDescriptor{
[[Value]]: undefined,
[[Writable]]: false,
[[Enumerable]]: false,
[[Configurable]]: true }.SecurityError" 7.2.1.3.3 IsPlatformObjectSameOrigin ( O )
w.document, this
step is invoked before the document getter is reached as part
of the [[Get]] algorithm for the WindowProxy
w.7.2.1.3.4 CrossOriginGetOwnPropertyHelper ( O, P )
SecurityError" CrossOriginPropertyFallback.7.2.1.3.5 CrossOriginGet ( O, P, Receiver )
SecurityError"
Call(getter, Receiver).7.2.1.3.6 CrossOriginSet ( O, P, V,
Receiver )
SecurityError" 7.2.1.3.7 CrossOriginOwnPropertyKeys ( O )
then",
@@toStringTag, @@hasInstance, @@isConcatSpreadable
».7.2.2 The
Window objectFirefox1+Safari1+Chrome1+
Opera3+Edge79+
Edge (Legacy)12+Internet Explorer4+
Firefox Android?Safari iOS?Chrome Android?WebView Android37+Samsung Internet?Opera Android10.1+[window.windowFirefox1+Safari3+Chrome1+
Opera12.1+Edge79+
Edge (Legacy)12+Internet Explorer4+
Firefox Android?Safari iOS1+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+window.framesFirefox1+Safari1+Chrome1+
Opera12.1+Edge79+
Edge (Legacy)12+Internet Explorer4+
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+window.selfFirefox1+Safari3+Chrome1+
Opera12.1+Edge79+
Edge (Legacy)12+Internet Explorer4+
Firefox Android?Safari iOS1+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+window.documentFirefox1+Safari1+Chrome1+
Opera12.1+Edge79+
Edge (Legacy)12+Internet Explorer4+
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+Document associated with window.document.defaultViewFirefox1+Safari1+Chrome1+
Opera12.1+Edge79+
Edge (Legacy)12+Internet Explorer9+
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+Window associated with document, if there is one, or null otherwise.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.Window's browsing context is
its associated Document's browsing context. It is either null or a
browsing context.Window's navigable is
the navigable whose active document is the
Window's associated
Document's, or null if there is no such navigable.window, frames, and self getter steps are to return this's relevant realm.[[GlobalEnv]].[[GlobalThisValue]].document getter steps
are to return this's associated
Document.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.defaultView getter steps are:WindowProxy object.
Firefox1+Safari1+Chrome1+
Opera12.1+Edge79+
Edge (Legacy)12+Internet Explorer4+
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+Window objects must also have a writable, configurable,
non-enumerable property named HTMLDocument whose value is the
Document interface object.7.2.2.1 Opening and closing windows
window = window.open([ url [, target [, features ] ] ])Firefox1+Safari1+Chrome1+
Opera3+Edge79+
Edge (Legacy)12+Internet Explorer4+
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android10.1+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"noopener and noreferrer link types on hyperlinks.popup"visible getter on all
BarProp objects as well.)globalThiswindow.name [ = value ]Firefox1+Safari1+Chrome1+
Opera12.1+Edge79+
Edge (Legacy)12+Internet Explorer4+
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+window.close()Firefox1+Safari1+Chrome1+
Opera3+Edge79+
Edge (Legacy)12+Internet Explorer4+
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android10.1+window.closedFirefox1+Safari1+Chrome1+
Opera12.1+Edge79+
Edge (Legacy)12+Internet Explorer4+
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+window.stop()Firefox1+Safari3+Chrome1+
Opera12.1+Edge79+
Edge (Legacy)14+Internet ExplorerNo
Firefox Android?Safari iOS1+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+Document._blank".noopener"] exists, then:noopener"] as a boolean
feature.noopener"].noreferrer"] exists, then:noreferrer"] as a boolean
feature.noreferrer"].no-referrer".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.new and unrestricted" or "new with no opener", then:about:blank.SyntaxError"
If urlRecord matches about:blank, then perform the
URL and history update steps given targetNavigable's active document and urlRecord.about:blank?foo. If url is just plain about:blank, this will do nothing.SyntaxError" Navigate targetNavigable to
urlRecord using sourceDocument, with referrerPolicy set to referrerPolicy and
exceptionsEnabled set to true.new with no
opener", then return null.WindowProxy.open(url, target,
features) method steps are to run the window open steps with
url, target, and features.
popup"] exists, then return the result of parsing
tokenizedFeatures["popup"] as a boolean
feature.location", and false.toolbar", and false.menubar", and false.resizable", and true.scrollbars", and false.status", and false.screenx"
left".
screeny"
top".
innerwidth"
width".
innerheight"
height".
yes", then return
true.true", then return
true.
name getter steps are:name setter steps are:
close() method steps
are:Window that does not
correspond to a top-level traversable, and so closing is not allowed.closed getter
steps are to return true if this's browsing context
is null or its is closing is true; otherwise false.stop() method steps
are:7.2.2.2 Indexed access on the
Window objectwindow.lengthFirefox1+Safari1+Chrome1+
Opera12.1+Edge79+
Edge (Legacy)12+Internet Explorer4+
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+window[index]WindowProxy corresponding to the indicated document-tree child navigables.length getter steps are
to return this's associated
Document's document-tree child navigables's size.WindowProxy object.7.2.2.3 Named access on the
Window objectwindow[name]document.getElementById() or document.querySelector().Window object window is the
return value of running these steps:Document.
https://example.org/, assuming https://elsewhere.example/
sets window.name to "spices", evaluating
window.spices after everything has loaded will yield undefined: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:name content attribute for all embed,
form, 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; andid 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.Window object window, the user agent must return the
value obtained using the following steps:Document's descendants whose
content navigable is in objects.WindowProxy.window's associated Document, whose filter matches
only named objects of window with
the name name. (By definition, these will all be elements.)Window object
window with the name name, for the purposes of the above algorithm, consist
of the following:Document whose target name is name;embed, form, 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; andid content attribute
whose value is name and are in a document tree with window's
associated Document as their
root.Window interface has the named properties objects rather than legacy platform objects.7.2.2.4 Accessing related windows
window.topFirefox1+Safari3+Chrome1+
Opera12.1+Edge79+
Edge (Legacy)12+Internet Explorer4+
Firefox Android4+Safari iOS1+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+WindowProxy for the top-level traversable.window.opener [ = value ]Firefox1+Safari1+Chrome1+
Opera3+Edge79+
Edge (Legacy)12+Internet Explorer9+
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android10.1+WindowProxy for the opener browsing context.window.parentFirefox1+Safari1.3+Chrome1+
Opera3+Edge79+
Edge (Legacy)12+Internet Explorer9+
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android10.1+WindowProxy for the parent
navigable.window.frameElementFirefox1+Safari3+Chrome1+
Opera12.1+Edge79+
Edge (Legacy)12+Internet Explorer5.5+
Firefox Android?Safari iOS1+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+top getter steps are:WindowProxy.opener getter steps
are:WindowProxy object.opener setter steps are:opener", {
[[Value]]: the given value, [[Writable]]: true, [[Enumerable]]: true, [[Configurable]]: true
}).
window.opener to null clears the opener
browsing context reference. In practice, this prevents future scripts from accessing their
opener browsing context's Window object.Window object through the window.opener getter.
E.g., a script can set window.opener.location, causing the opener
browsing context to navigate.parent getter steps
are:WindowProxy.frameElement
getter steps are:
iframeWindow
was nulled out when element was
removed from the document.7.2.2.5 Historical browser interface element APIs
Window interface had some properties that represented
the visibility of certain web browser interface elements.Window's browsing context's
is popup property is true or false.BarProp object:Firefox1+Safari3+Chrome1+
Opera?Edge79+
Edge (Legacy)12+Internet ExplorerNo
Firefox Android?Safari iOS1+Chrome Android?WebView Android37+Samsung Internet?Opera Android?[window.locationbar.visibleFirefox1+Safari3+Chrome1+
Opera?Edge79+
Edge (Legacy)12+Internet ExplorerNo
Firefox Android?Safari iOS1+Chrome Android?WebView Android?Samsung Internet?Opera Android?window.menubar.visibleFirefox1+Safari3+Chrome1+
Opera?Edge79+
Edge (Legacy)12+Internet ExplorerNo
Firefox Android?Safari iOS1+Chrome Android?WebView Android?Samsung Internet?Opera Android?window.personalbar.visibleFirefox1+Safari3+Chrome1+
Opera12.1+Edge79+
Edge (Legacy)12+Internet ExplorerNo
Firefox Android?Safari iOS1+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+window.scrollbars.visibleFirefox1+Safari3+Chrome1+
Opera12.1+Edge79+
Edge (Legacy)12+Internet ExplorerNo
Firefox Android?Safari iOS1+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+window.statusbar.visibleFirefox1+Safari3+Chrome1+
Opera?Edge79+
Edge (Legacy)12+Internet ExplorerNo
Firefox Android?Safari iOS1+Chrome Android?WebView Android?Samsung Internet?Opera Android?window.toolbar.visibleFirefox1+Safari3+Chrome1+
Opera?Edge79+
Edge (Legacy)12+Internet ExplorerNo
Firefox Android?Safari iOS1+Chrome Android?WebView Android?Samsung Internet?Opera Android?Window is not a popup; otherwise, returns false.Firefox1+Safari3+Chrome1+
Opera?Edge79+
Edge (Legacy)12+Internet ExplorerNo
Firefox Android?Safari iOS1+Chrome Android?WebView Android37+Samsung Internet?Opera Android?visible getter
steps are:BarProp objects must exist for each Window object:BarProp objectBarProp objectBarProp objectBarProp objectBarProp objectBarProp objectlocationbar
attribute must return the location bar BarProp object.menubar
attribute must return the menu bar BarProp object.personalbar
attribute must return the personal bar BarProp object.scrollbars
attribute must return the scrollbar BarProp object.statusbar
attribute must return the status bar BarProp object.toolbar
attribute must return the toolbar BarProp object.
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.7.2.2.6 Script settings for
Window objectsDocument.Document.Document.Document.concrete", andDocument is allowed to use the "cross-origin-isolated" feature.Document's load timing info's navigation start
time.7.2.3 The
WindowProxy exotic objectWindowProxy 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.WindowProxy exotic object must use the ordinary internal methods except where
it is explicitly specified otherwise below.WindowProxy interface object.WindowProxy object has a [[Window]] internal slot representing the wrapped Window object.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.7.2.3.1 [[GetPrototypeOf]] ( )
7.2.3.2 [[SetPrototypeOf]] ( V )
7.2.3.3 [[IsExtensible]] ( )
7.2.3.4 [[PreventExtensions]] ( )
7.2.3.5 [[GetOwnProperty]] ( P )
Document.Document earlier than
navigableB's container was.WindowProxy.WindowProxy of the named
object of W with the name P.7.2.3.6 [[DefineOwnProperty]] ( P, Desc
)
SecurityError" 7.2.3.7 [[Get]] ( P, Receiver )
7.2.3.8 [[Set]] ( P, V, Receiver )
7.2.3.9 [[Delete]] ( P )
SecurityError" 7.2.3.10 [[OwnPropertyKeys]] ( )
Document's document-tree
child navigables's size.7.2.4 The
Location interfaceFirefox1+Safari1+Chrome1+
Opera3+Edge79+
Edge (Legacy)12+Internet Explorer4+
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android10.1+Firefox1+Safari1+Chrome1+
Opera3+Edge79+
Edge (Legacy)12+Internet Explorer3+
Firefox Android?Safari iOS?Chrome Android?WebView Android37+Samsung Internet?Opera Android10.1+Firefox1+Safari1+Chrome1+
Opera3+Edge79+
Edge (Legacy)12+Internet Explorer4+
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android10.1+Window object is associated with a unique instance of a Location
object, allocated when the Window object is created.Location exotic object is defined through a mishmash of IDL,
invocation of JavaScript internal methods post-creation, and overridden JavaScript internal
methods. Coupled with its scary security policy, please take extra care while implementing
this excrescence.Location object, run these steps:Location platform
object.valueOf", {
[[Value]]: valueOf,
[[Writable]]: false,
[[Enumerable]]: false,
[[Configurable]]: false }).valueOf and @@toPrimitive own
data properties, as well as the fact that all of Location's IDL attributes are marked
[LegacyUnforgeable], is required by legacy code that consulted
the Location interface, or stringified it, to determine the document URL, and then used it in a security-sensitive way.
In particular, the valueOf, @@toPrimitive, and [LegacyUnforgeable] stringifier mitigations ensure that code such as
foo[location] = bar or location + "" cannot be
misdirected.document.location [ = value ]window.location [ = value ]Location object with the current page's location.Document object's location getter steps are to return
this's relevant global object's Location object, if
this is fully active, and null otherwise.Window object's location getter steps are to return this's
Location object.Location objects provide a representation of the URL of their associated Document, as well as
methods for navigating and reloading
the associated navigable.[location.toString()location.hrefFirefox1+Safari1+Chrome1+
Opera12.1+Edge79+
Edge (Legacy)12+Internet Explorer3+
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+Firefox22+Safari1+Chrome52+
Opera?Edge79+
Edge (Legacy)12+Internet Explorer11
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android?Location object's URL.location.originFirefox21+Safari5.1+Chrome8+
Opera?Edge79+
Edge (Legacy)12+Internet Explorer11
Firefox Android?Safari iOS?Chrome Android?WebView Android3+Samsung Internet?Opera Android?Location object's URL's origin.location.protocolFirefox1+Safari1+Chrome1+
Opera12.1+Edge79+
Edge (Legacy)12+Internet Explorer3+
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+Location object's URL's scheme.location.hostFirefox1+Safari1+Chrome1+
Opera12.1+Edge79+
Edge (Legacy)12+Internet Explorer3+
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+Location object's URL's host and port (if different from the default
port for the scheme).location.hostnameFirefox1+Safari1+Chrome1+
Opera12.1+Edge79+
Edge (Legacy)12+Internet Explorer3+
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+Location object's URL's host.location.portFirefox1+Safari1+Chrome1+
Opera12.1+Edge79+
Edge (Legacy)12+Internet Explorer3+
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+Location object's URL's port.location.pathnameFirefox1+Safari1+Chrome1+
Opera12.1+Edge79+
Edge (Legacy)12+Internet Explorer3+
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+Location object's URL's path.location.searchFirefox1+Safari1+Chrome1+
Opera12.1+Edge79+
Edge (Legacy)12+Internet Explorer3+
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+Location object's URL's query (includes leading "?" if non-empty).?").location.hashFirefox1+Safari1+Chrome1+
Opera12.1+Edge79+
Edge (Legacy)12+Internet Explorer3+
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+Location object's URL's fragment (includes leading "#" if non-empty).#").location.assign(url)Firefox1+Safari3+Chrome1+
Opera3+Edge79+
Edge (Legacy)12+Internet Explorer5.5+
Firefox Android?Safari iOS1+Chrome Android?WebView Android?Samsung Internet?Opera Android10.1+location.replace(url)Firefox1+Safari1+Chrome1+
Opera3+Edge79+
Edge (Legacy)12+Internet Explorer5.5+
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android10.1+location.reload()Firefox1+Safari1+Chrome1+
Opera3+Edge79+
Edge (Legacy)12+Internet Explorer5.5+
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android10.1+location.ancestorOriginsFirefoxNoSafari6+Chrome20+
Opera?Edge79+
Edge (Legacy)?Internet ExplorerNo
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android?DOMStringList object listing the origins of the ancestor navigables' active documents.Location object has an associated relevant Document,
which is its relevant global object's browsing context's active document, if this
Location object's relevant global object's browsing context is non-null, and null otherwise.Location object has an associated url,
which is this Location object's relevant Document's URL, if this Location object's relevant
Document is non-null, and about:blank otherwise.Location object has an associated ancestor origins list. When a
Location object is created, its ancestor origins list must be set to a
DOMStringList object whose associated list is the list of strings that
the following steps would produce:Location object's relevant
Document.Location-object navigate a Location object
location to a URL url, optionally given a history
handling behavior historyHandling (default "auto"):Document.Document is not yet
completely loaded, and the incumbent global
object does not have transient activation, then set
historyHandling to "replace".href getter
steps are:Document is non-null and its
origin is not same origin-domain with
the entry settings object's origin, then throw a
"SecurityError" this's url, serialized.href setter steps are:Document is null, then
return.SyntaxError"
Location-object navigate this to
url.href setter intentionally has no
security check.origin
getter steps are:Document is non-null and its
origin is not same origin-domain with
the entry settings object's origin, then throw a
"SecurityError" serialization of
this's url's origin.protocol
getter steps are:Document is non-null and its
origin is not same origin-domain with
the entry settings object's origin, then throw a
"SecurityError" this's url's scheme, followed by ":".protocol setter steps are:Document is null, then
return.Document's origin is not same origin-domain with the
entry settings object's origin, then throw a
"SecurityError" copyURL be a copy of this's url.:", with copyURL
as url and scheme start state as
state override.https:" (or even "https::::") is the same as
providing a value of "https".SyntaxError" copyURL's scheme is not an
HTTP(S) scheme, then terminate these steps.Location-object navigate this to
copyURL.host getter
steps are:Document is non-null and its
origin is not same origin-domain with
the entry settings object's origin, then throw a
"SecurityError" url be this's url.:" and url's port, serialized.host setter steps are:Document is null, then
return.Document's origin is not same origin-domain with the
entry settings object's origin, then throw a
"SecurityError" copyURL be a copy of this's url.Location-object navigate this to
copyURL.hostname
getter steps are:Document is non-null and its
origin is not same origin-domain with
the entry settings object's origin, then throw a
"SecurityError" this's url's host is null, return the empty string.hostname setter steps are:Document is null, then
return.Document's origin is not same origin-domain with the
entry settings object's origin, then throw a
"SecurityError" copyURL be a copy of this's url.Location-object navigate this to
copyURL.port getter
steps are:Document is non-null and its
origin is not same origin-domain with
the entry settings object's origin, then throw a
"SecurityError" this's url's port is null, return the empty string.port setter steps are:Document is null, then
return.Document's origin is not same origin-domain with the
entry settings object's origin, then throw a
"SecurityError" copyURL be a copy of this's url.Location-object navigate this to
copyURL.pathname
getter steps are:Document is non-null and its
origin is not same origin-domain with
the entry settings object's origin, then throw a
"SecurityError" URL path serializing this
Location object's url.pathname setter steps are:Document is null, then
return.Document's origin is not same origin-domain with the
entry settings object's origin, then throw a
"SecurityError" copyURL be a copy of this's url.Location-object navigate this to
copyURL.search
getter steps are:Document is non-null and its
origin is not same origin-domain with
the entry settings object's origin, then throw a
"SecurityError" this's url's query is either null or the empty string, return the empty
string.search setter steps are:Document is null, then
return.Document's origin is not same origin-domain with the
entry settings object's origin, then throw a
"SecurityError" copyURL be a copy of this's url.?" removed, if any.Document's document's character encoding,
copyURL as url, and query
state as state
override.Location-object navigate this to
copyURL.hash getter
steps are:Document is non-null and its
origin is not same origin-domain with
the entry settings object's origin, then throw a
"SecurityError" this's url's fragment is either null or the empty string, return the
empty string.hash setter steps are:Document is null, then
return.Document's origin is not same origin-domain with the
entry settings object's origin, then throw a
"SecurityError" copyURL be a copy of this's url.#"
removed, if any.location.hash on scroll. It does not apply to other
mechanisms of fragment navigation, such as the location.href setter or location.assign().Location-object navigate this to
copyURL.a and area elements,
the hash setter does not special case the empty string, to
remain compatible with deployed scripts.
assign(url) method steps are:Document is null, then
return.Document's origin is not same origin-domain with the
entry settings object's origin, then throw a
"SecurityError" urlRecord be the result of encoding-parsing a URL given
url, relative to the entry settings object.SyntaxError"
Location-object navigate this to
urlRecord.replace(url) method steps are:Document is null, then
return.SyntaxError"
Location-object navigate this to
urlRecord given "replace".replace() method intentionally has
no security check.reload() method
steps are:Document.SecurityError" Reload document's node navigable.
ancestorOrigins getter steps are:Document is null, then return
an empty list.Document's origin is not same origin-domain with the
entry settings object's origin, then throw a
"SecurityError" this's ancestor origins list.ancestorOrigins attribute works are still
controversial and might change. See issue
#1918 for more information.
Location exotic object
requires additional logic beyond IDL for security purposes. The Location object must
use the ordinary internal methods except where it is explicitly specified otherwise below.Location object has a [[DefaultProperties]] internal slot
representing its own properties at time of its creation.7.2.4.1 [[GetPrototypeOf]] ( )
7.2.4.2 [[SetPrototypeOf]] ( V )
7.2.4.3 [[IsExtensible]] ( )
7.2.4.4 [[PreventExtensions]] ( )
7.2.4.5 [[GetOwnProperty]] ( P )
7.2.4.6 [[DefineOwnProperty]] ( P, Desc )
SecurityError" 7.2.4.7 [[Get]] ( P, Receiver )
7.2.4.8 [[Set]] ( P, V, Receiver )
7.2.4.9 [[Delete]] ( P )
SecurityError" 7.2.4.10 [[OwnPropertyKeys]] ( )
7.2.5 The
History interfaceFirefox1+Safari1+Chrome1+
Opera3+Edge79+
Edge (Legacy)12+Internet Explorer10+
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android10.1+Firefox1+Safari1+Chrome1+
Opera3+Edge79+
Edge (Legacy)12+Internet Explorer4+
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android10.1+history.lengthFirefox1+Safari1+Chrome1+
Opera12.1+Edge79+
Edge (Legacy)12+Internet Explorer10+
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+history.scrollRestorationFirefox46+Safari11+Chrome46+
Opera?Edge79+
Edge (Legacy)?Internet ExplorerNo
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android?history.scrollRestoration = valuehistory.stateFirefox4+Safari6+Chrome19+
Opera12.1+Edge79+
Edge (Legacy)12+Internet Explorer10+
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+history.go()history.go(delta)Firefox1+Safari1+Chrome1+
Opera12.1+Edge79+
Edge (Legacy)12+Internet Explorer10+
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+history.back()Firefox1+Safari1+Chrome1+
Opera12.1+Edge79+
Edge (Legacy)12+Internet Explorer10+
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+history.forward()Firefox1+Safari1+Chrome1+
Opera12.1+Edge79+
Edge (Legacy)12+Internet Explorer10+
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+history.pushState(data, "")Firefox4+Safari5+Chrome5+
Opera11.5+Edge79+
Edge (Legacy)12+Internet Explorer10+
Firefox Android?Safari iOS4+Chrome Android?WebView Android37+Samsung Internet?Opera Android11.5+history.pushState(data, "", url)Document cannot have
its URL rewritten to url, a "SecurityError"
history.replaceState(data, "")Firefox4+Safari5+Chrome5+
Opera11.5+Edge79+
Edge (Legacy)12+Internet Explorer10+
Firefox Android?Safari iOS4+Chrome Android?WebView Android37+Samsung Internet?Opera Android11.5+history.replaceState(data, "", url)Document cannot have
its URL rewritten to url, a "SecurityError"
Document has a history object, a
History object.history getter steps
are to return this's associated
Document's history object.
History object has state,
initially null.History object has a length, a
non-negative integer, initially 0.History object has an index, a
non-negative integer, initially 0.length getter
steps are:Document is not fully
active, then throw a "SecurityError"
this's length.scrollRestoration getter steps are:Document is not fully
active, then throw a "SecurityError"
this's node navigable's active session history entry's scroll restoration mode.scrollRestoration setter steps
are:Document is not fully
active, then throw a "SecurityError"
this's node navigable's active session history entry's scroll restoration mode to the given value.state getter
steps are:Document is not fully
active, then throw a "SecurityError"
this's state.go(delta)
method steps are to delta traverse this given delta.back() method steps
are to delta traverse this given −1.forward() method
steps are to delta traverse this given +1.History object history given an integer
delta:Document.SecurityError" delta is 0, then reload document's node
navigable.pushState(data,
unused, url) method steps are to run the shared history
push/replace state steps given this, data, url, and
"push".replaceState(data, unused,
url) method steps are to run the shared history push/replace state
steps given this, data, url, and "replace".History
history, a value data, a scalar value string-or-null
url, and a history handling behavior historyHandling, are:Document.SecurityError" SecurityError"
document cannot have its URL
rewritten to newURL, then throw a "SecurityError"
The special case for the empty string here is historical, and leads to
different resulting URLs when comparing code such as location.href = ""
(which performs URL parsing on the empty string) versus history.pushState(null, "", "") (which bypasses it).navigate event at
navigation with navigationType set to
historyHandling, isSameDocument set
to true, destinationURL set to
newURL, and classicHistoryAPIState set to
serializedData.Document object in the session history
after having added the new entry. (Thus the state history acts as a FIFO buffer for eviction, but
as a LIFO buffer for navigation.)Document document can have its URL rewritten to a
URL targetURL if the following algorithm returns true:http: and https: URLs.)file", and targetURL and documentURL differ in their
path component, then return false. (Differences in query and fragment
are allowed for file: URLs.)
document's URL
targetURL
can have its URL rewritten
https://example.com/home
https://example.com/home#about
✅
https://example.com/home
https://example.com/home?page=shop
✅
https://example.com/home
https://example.com/shop
✅
https://example.com/home
https://user:[email protected]/home
❌
https://example.com/home
http://example.com/home
❌
file:///path/to/x
file:///path/to/x#hash
✅
file:///path/to/x
file:///path/to/x?search
✅
file:///path/to/x
file:///path/to/y
❌
about:blank
about:blank#hash
✅
about:blank
about:blank?search
❌
about:blank
about:srcdoc
❌
data:text/html,foo
data:text/html,foo#hash
✅
data:text/html,foo
data:text/html,foo?search
❌
data:text/html,foo
data:text/html,bar
❌
data:text/html,foo
data:bar
❌
blob:https://example.com/77becafe-657b-4fdc-8bd3-e83aaa5e8f43
blob:https://example.com/77becafe-657b-4fdc-8bd3-e83aaa5e8f43#hash
✅
blob:https://example.com/77becafe-657b-4fdc-8bd3-e83aaa5e8f43
blob:https://example.com/77becafe-657b-4fdc-8bd3-e83aaa5e8f43?search
❌
blob:https://example.com/77becafe-657b-4fdc-8bd3-e83aaa5e8f43
blob:https://example.com/anything
❌
blob:https://example.com/77becafe-657b-4fdc-8bd3-e83aaa5e8f43
blob:path
❌
Document
matters, and not its origin. They can mismatch in
cases like about:blank Documents with inherited origins, in sandboxed
iframes, or when the document.domain
setter has been used.
pushState() method is the same information as would be sent
to the server, but in a more convenient form, so that the script doesn't have to parse the URL
each time the user navigates.
scrollRestoration attribute as soon as possible
(e.g., in the first script element in the document's head element) to
ensure that any entry added to the history session gets the desired scroll restoration mode.7.2.6 The navigation API
7.2.6.1 Introduction
navigation
property, provides a modern and web application-focused way of managing navigations and history entries. It is a successor to the classic location and history APIs.navigation.entries() array contains NavigationHistoryEntry instances, which have other useful properties in addition to the url and index properties shown here. Note that the array only contains NavigationHistoryEntry objects that represent the current navigable, and thus its contents are not impacted by navigations inside navigable containers such as iframes, or by navigations of the parent navigable in cases where the navigation API is itself being used inside an iframe. Additionally, it only contains NavigationHistoryEntry objects representing same-origin session history entries, meaning that if the user has visited other origins before or after the current one, there will not be corresponding NavigationHistoryEntrys.
navigation.canGoBack will be false if the previous session history entry is for a page from another origin.
navigate event, which fires whenever almost any navigation or traversal occurs in the current navigable:navigation:navigationtraverse" navigations, such as those taking place inside child navigables, those crossing to new origins, or when the user attempts to traverse again shortly after a previous call to prevented them from doing so.NavigateEvent's intercept() method allows intercepting a navigation and converting it into a same-document navigation:navigationhandler function can return a promise to represent the asynchronous progress, and success or failure, of the navigation. While the promise is still pending, browser UI can treat the navigation as ongoing (e.g., by presenting a loading spinner). Other parts of the navigation API are also sensitive to these promises, such as the return value of navigation.navigate():
7.2.6.2 The
Navigation interface[Window has an associated navigation
API, which is a Navigation object. Upon creation of the Window
object, its navigation API must be set to a
new Navigation object created in the Window object's relevant realm.navigation getter
steps are to return this's navigation
API.Navigation interface:Event handler
Event handler event type
onnavigate
navigate
onnavigatesuccess
navigatesuccess
onnavigateerror
navigateerror
oncurrententrychange
currententrychange
7.2.6.3 Core infrastructure
Navigation has an associated entry
list, a list of NavigationHistoryEntry objects, initially
empty.Navigation has an associated current entry index, an integer, initially
−1.Navigation
navigation is the result of running the following steps:Navigation navigation has entries and events disabled if
the following steps return true:Document.about:blank is true, then
return true.Navigation navigation:
NavigationType
enumeration:push"push", or to
history.pushState().replace"replace", or
to history.replaceState().reload"traverse"NavigationType enumeration is a superset of
the value space of the specification-internal history handling behavior type. Several
parts of this standard make use of this overlap, by passing in a history handling
behavior to an algorithm that expects a NavigationType.7.2.6.4 Initializing and updating the entry list
Navigation navigation, a list of session history entries newSHEs, and a session history
entry initialSHE:NavigationHistoryEntry created
in the relevant realm of
navigation.Navigation navigation, a list of session history entries newSHEs, and a session history
entry reactivatedSHE:NavigationHistoryEntry matchingOldNHE whose session history entry is newSHE, then:NavigationHistoryEntry
created in the relevant realm of
navigation.NavigationHistoryEntrys that remain in
oldNHEs represent session history entries
which have been disposed while the Document was in bfcache.dispose at disposedNHE.
dispose
events will fire after the pageshow event. This ensures
that pageshow is the first event a page receives upon
reactivation.pageshow event fires. This ensures that navigation.entries() and navigation.currentEntry will have correctly-updated
values during any pageshow event handlers.)Navigation navigation, a session history entry
destinationSHE, and a NavigationType navigationType:traverse",
then:push", then:replace", then:push" or
"replace", then:NavigationHistoryEntry created
in the relevant realm of
navigation.dispose or currententrychange events, since event handlers could
start another navigation, or otherwise change the value of navigation's ongoing
API method tracker.currententrychange at navigation using
NavigationCurrentEntryChangeEvent, with its navigationType attribute
initialized to navigationType and its from initialized to
oldCurrentNHE.dispose at disposedNHE.7.2.6.5 The
NavigationHistoryEntry interface[entry.urlDocument than the
current one (i.e., if sameDocument
is false), and that Document was fetched with a referrer policy of
"no-referrer" or "origin", since that indicates
the Document in question is hiding its URL even from other same-origin pages.entry.keyNavigationHistoryEntry instances that replace this one due to "replace" navigations, and will survive reloads and
session restores.navigation.traverseTo(key).entry.idNavigationHistoryEntry
instances. This value will survive reloads and session restores.entry.indexNavigationHistoryEntry within navigation.entries(), or −1 if the entry is not in
the navigation history entry list.entry.sameDocumentDocument as the current one, or not. This will be true, for example, when the entry
represents a fragment navigation or single-page app navigation.entry.getState()navigation.navigate() or navigation.updateCurrentEntry(). This state
survives reloads and session restores.entry.getState() !== entry.getState(), since a fresh deserialization is
returned each time.history.state.NavigationHistoryEntry has an associated session
history entry, which is a session history entry.NavigationHistoryEntry nhe is given by the return value of the following
algorithm:Document is not fully
active, then return the empty string.NavigationHistoryEntry nhe is given by the return value of the following
algorithm:Document is not fully
active, then return the empty string.NavigationHistoryEntry nhe is given by the return value of the following
algorithm:Document is not fully
active, then return −1.url getter steps are:Document.no-referrer" or "origin", then
return null.key getter steps are to return
this's key.id getter steps are to return
this's ID.index getter steps are to return
this's index.sameDocument getter steps are:Document.getState() method steps are:Document is not fully
active, then return undefined.
NavigationHistoryEntry interface:Event handler
Event handler event type
ondispose
dispose
7.2.6.6 The history entry list
entries = navigation.entries()NavigationHistoryEntry instances represent the current
navigation history entry list, i.e., all session history
entries for this navigable that are same origin and contiguous
to the current session history entry.navigation.currentEntryNavigationHistoryEntry corresponding to the current session history entry.navigation.updateCurrentEntry({ state })navigation.reload() would do.navigation.navigate() or navigation.reload(), which will trigger a navigate event.navigation.canGoBackcurrentEntry) is
not the first one in the navigation history entry list (i.e., in entries()). This means that there is a previous
session history entry for this navigable, and its document state's origin is same origin with the current
Document's origin.navigation.canGoForwardcurrentEntry) is
not the last one in the navigation history entry list (i.e., in entries()). This means that there is a next session
history entry for this navigable, and its document state's origin is same origin with the current
Document's origin.entries()
method steps are:navigation.entries() !== navigation.entries().currentEntry getter steps are to return the
current entry of this.updateCurrentEntry(options)
method steps are:InvalidStateError"
serializedState be
StructuredSerializeForStorage(options["state"]), rethrowing any
exceptions.currententrychange at this using
NavigationCurrentEntryChangeEvent, with its navigationType attribute
initialized to null and its from
initialized to current.canGoBack getter steps are:canGoForward getter steps are:7.2.6.7 Initiating navigations
{ committed, finished } = navigation.navigate(url){ committed, finished } = navigation.navigate(url, options)history can be set to
"replace" to replace the current
session history entry, instead of pushing a new one.info can be set to any value; it
will populate the info property of the
corresponding NavigateEvent.state can be set to any
serializable value; it will populate the state
retrieved by navigation.currentEntry.getState() once the
navigation completes, for same-document navigations. (It will be ignored for navigations that
end up cross-document.)navigateEvent.intercept() method can
be used to convert it into a same-document navigation.AbortError" navigateEvent.intercept() method, committed will fulfill immediately, and finished will fulfill or reject according to any
promsies returned by handlers passed to intercept().Content-Disposition: attachment` header fields from
the server (and thus do not actually navigate), both promises will never settle.NavigationHistoryEntry that was navigated to.{ committed, finished } = navigation.reload(options)info and state, which behave as described above.navigateEvent.intercept() method. Doing so will mean
this call only updates state or passes along the appropriate info, plus performing whater actions the navigate event handlers see fit to carry out.navigateEvent.intercept() method, committed will fulfill immediately, and finished will fulfill or reject according to any
promsies returned by handlers passed to intercept().{ committed, finished } = navigation.traverseTo(key){ committed, finished } = navigation.traverseTo(key, { info })NavigationHistoryEntry with the given
key. info can be set to any value;
it will populate the info property of the
corresponding NavigateEvent.info will be ignored.NavigationHistoryEntry in navigation.entries() whose key matches key, both promises will
reject with an "InvalidStateError"
navigateEvent.intercept() method, committed will fulfill as soon as the traversal
is processed and navigation.currentEntry is
updated, and finished will fulfill or
reject according to any promsies returned by the handlers passed to intercept().navigation.currentEntry is updated.Content-Disposition: attachment` header fields from
the server (and thus do not actually traverse), both promises will never settle.{ committed, finished } = navigation.back(key){ committed, finished } = navigation.back(key, { info })NavigationHistoryEntry and thus will cause navigation.currentEntry to change. info can be set to any value; it will populate the
info property of the corresponding
NavigateEvent.info will be ignored.traverseTo().{ committed, finished } = navigation.forward(key){ committed, finished } = navigation.forward(key, { info })NavigationHistoryEntry and thus will cause navigation.currentEntry to change. info can be set to any value; it will populate the
info property of the corresponding
NavigateEvent.info will be ignored.traverseTo().navigate(options) method steps are:SyntaxError" document be this's relevant global object's associated Document.history"] is "push", and the navigation must be a
replace given urlRecord and document, then return an early error result for a
"NotSupportedError" state"], if it exists; otherwise, undefined.InvalidStateError" InvalidStateError" info be options["info"], if it exists;
otherwise, undefined.history"] and navigationAPIState set to
serializedState.location.assign() and friends,
which are exposed across origin-domain boundaries,
navigation.navigate() can only be accessed by code
with direct synchronous access to the window.navigation
property. Thus, we avoid the complications about attributing the source document of the
navigation, and we don't need to deal with the allowed by sandboxing to navigate
check and its acccompanying exceptionsEnabled flag. We just
treat all navigations as if they come from the Document corresponding to this
Navigation object itself (i.e., document).navigate event
firing algorithm which would promote that upcoming API method tracker to ongoing.AbortError" reload(options) method steps are:Document.state"] exists, then set serializedState to
StructuredSerializeForStorage(options["state"]). If this throws an exception, then
return an early error result for that
exception.InvalidStateError" InvalidStateError" info be options["info"], if it exists;
otherwise, undefined.traverseTo(key, options)
method steps are:InvalidStateError"
this's entry list does not
contain a NavigationHistoryEntry whose session history entry's navigation
API key equals key, then return an early error result for an
"InvalidStateError" performing a navigation API traversal given
this, key, and options.back(options) method steps are:InvalidStateError" key be this's entry
list[this's current entry
index − 1]'s session history entry's navigation API key.forward(options) method steps are:InvalidStateError" key be this's entry
list[this's current entry
index + 1]'s session history entry's navigation API key.Navigation navigation, a string key, and a
NavigationOptions options:Document.InvalidStateError" InvalidStateError" current be the current entry
of navigation.committed" → a promise resolved
with current, "finished"
→ a promise resolved with current ]».info"], if it exists;
otherwise, undefined.InvalidStateError"
none".canceled-by-beforeunload", then
queue a global task on the navigation and traversal task source given
navigation's relevant global object to reject the finished
promise for apiMethodTracker with a new
"AbortError" navigation's relevant realm.initiator-disallowed", then queue a
global task on the navigation and traversal task source given
navigation's relevant global object to reject the finished
promise for apiMethodTracker with a new
"SecurityError" navigation's relevant realm.
canceled-by-beforeunload" or "initiator-disallowed", the navigate
event was never fired, aborting the ongoing
navigation would not be correct; it would result in a navigateerror event without a preceding navigate event.canceled-by-navigate" case, navigate is fired, but the inner navigate event firing algorithm will take care of
aborting the ongoing navigation.NavigationResult dictionary instance given by «[ "committed" → a promise rejected with
e, "finished" → a promise
rejected with e ]».NavigationResult dictionary instance given by «[ "committed" apiMethodTracker's committed promise, "finished" → apiMethodTracker's finished promise ]».7.2.6.8 Ongoing navigation tracking
Navigation object needs to keep track of the following:State
Duration
Explanation
The NavigateEvent
For the duration of event firing
So that if the navigation is canceled while the event is firing, we can cancel the event
The event's abort controller
Until all promises returned from handlers passed to intercept() have settled
So that if the navigation is canceled, we can signal abort
Whether a new element was focused
Until all promises returned from handlers passed to intercept() have settled
So that if one was, focus is not reset
The NavigationHistoryEntry being navigated to
From when it is determined, until all promises returned from handlers passed to intercept() have settled
So that we know what to resolve any committed and finished promises with
Any finished promise that was returned
Until all promises returned from handlers passed to intercept() have settled
So that we can resolve or reject it appropriately
traverse" navigationsState
Duration
Explanation
Any state
For the duration of event firing
So that we can update the current entry's navigation API state if the event finishes firing without being canceled
traverse" navigationsState
Duration
Explanation
Any info
Until the task is queued to fire the navigate event
So that we can use it to fire the navigate after the trip through the session history traversal queue.
Any committed promise that was returned
Until the session history is updated (inside that same task)
So that we can resolve or reject it appropriately
Whether intercept() was called
Until the session history is updated (inside that same task)
So that we can suppress the normal scroll restoration logic in favor of the behavior given by the scroll option
url2, we still have the promise p1 around so that we can
reject it. We can't just get rid of any ongoing navigation promises the moment the second call to
navigate() happens.Navigation:navigate event, a
NavigateEvent or null, initially null.NavigationNavigationHistoryEntry or nullNavigation navigation, a JavaScript value info, and a
serialized state-or-null serializedState:NavigationHistoryEntry object for such Documents, and so we
have nothing to resolve them with); there is no NavigationHistoryEntry to apply
serializedState to; and there is no navigate
event to include info with. So, we don't need to track this API method call after
all.Navigation
navigation, a string destinationKey, and a JavaScript value
info:Navigation
navigation and a string-or-null destinationKey:NavigationHistoryEntry
nhe:navigation.traverseTo(), which does not allow changing
the state.Navigation
navigation and an optional error:navigate event.AbortError" navigation's relevant realm.navigate
event to null.navigateerror at navigation using
ErrorEvent, with error initialized to
error, and message, filename, lineno, and colno initialized to appropriate values
that can be extracted from error and the current JavaScript stack in the same
underspecified way that the report the exception algorithm does.window.stop(), these properties would probably end up
initialized based on the line of script that called window.stop(). But if it's because the user clicked the stop
button, these properties would probably end up with default values like the empty string or
0.navigate
event is null, then return.AbortError"
navigation's relevant realm.
navigation.transition property, which is an instance of
the NavigationTransition interface:[navigation.transitionNavigationTransition representing any ongoing navigation that hasn't yet
reached the navigatesuccess or navigateerror stage, if one exists; or null, if there is no
such transition ongoing.navigation.currentEntry (and other
properties like location.href) are updated immediately
upon navigation, this navigation.transition
property is useful for determining when such navigations are not yet fully settled, according to
any handlers passed to navigateEvent.intercept().navigation.transition.navigationTypepush", "replace", "reload", or "traverse", indicating what type of navigation this
transition is for.navigation.transition.fromNavigationHistoryEntry from which the transition is coming. This can be
useful to compare against navigation.currentEntry.navigation.transition.finishednavigatesuccess fires, or rejects at the same time the
navigateerror event fires.Navigation has a transition, which is a
NavigationTransition or null, initially null.transition getter steps are to return
this's transition.NavigationTransition has an associated navigation type, which is a
NavigationType.NavigationTransition has an associated from entry, which is a
NavigationHistoryEntry.NavigationTransition has an associated finished promise, which is a promise.navigationType getter steps are to
return this's navigation
type.from getter steps are to return
this's from entry.finished getter steps are to return
this's finished
promise.7.2.6.9 The
navigate eventnavigate
event. This event is fired on any navigation (in the broad sense of
the word), allowing web developers to monitor such outgoing navigations. In many cases, the
event is intercept() method of the NavigateEvent
class.7.2.6.9.1 The
NavigateEvent interface[event.navigationTypepush", "replace", "reload", or "traverse", indicating what type of navigation this
is.event.destinationNavigationDestination representing the destination of the
navigation.event.canInterceptintercept() can be called to
intercept this navigation and convert it into a same-document navigation, replacing its usual
behavior; false otherwise.Document can
have its URL rewritten to the destination URL, except for in the case of cross-document
"traverse" navigations, where it will always
be false.event.userInitiateda element,
submitting a form element, or using the browser UI
to navigate; false otherwise.event.hashChangeevent.signal
, which they perform as part of handling this navigation.event.formDatapush" or "replace" navigation representing a POST form submission; null otherwise.reload"
or "traverse" navigations that are revisiting
a session history entry that was originally created from a form submission.)event.downloadRequesta or area element's download attribute:download attribute's value. (This could be the empty
string.)push" navigation for unspecified reasons.Content-Disposition: attachment` header.navigate event will not fire at
all for downloads initiated using browser UI affordances, e.g., those created by right-clicking
and choosing to save the target of a link.event.infoevent.hasUAVisualTransitionevent.intercept({ handler, focusReset, scroll })handler option can be a
function that returns a promise. The handler function will run after the navigate event has finished firing, and the navigation.currentEntry property has been
synchronously updated. This returned promise is used to signal the duration, and success or
failure, of the navigation. After it settles, the browser signals to the user (e.g., via a
loading spinner UI, or assistive technology) that the navigation is finished. Additionally, it
fires navigatesuccess or navigateerror events as appropriate, which other parts of
the web application can respond to.autofocus attribute set, or the body element if
the attribute isn't present. The focusReset option can be set to "manual" to avoid this behavior.traverse" or "reload" navigations, or its
scroll-reset/scroll-to-a-fragment logic for "push"
or "replace" navigations, until any handlers'
returned promises settle. The scroll
option can be set to "manual" to turn
off any browser-driven scroll behavior entirely for this navigation, or scroll() can be called before the promise settles to
trigger this behavior early.SecurityError" canIntercept is false, or if "InvalidStateError"
event.scroll()traverse" or "reload" navigations, restores the scroll position
using the browser's usual scroll restoration logic.push" or "replace" navigations, either resets the scroll
position to the top of the document or scrolls to the fragment specified by destination.url if there is one.scroll option
being left as "after-transition", or called
before the navigation has committed, this method will throw an
"InvalidStateError"
NavigateEvent has an interception state, which is either "none", "intercepted", "committed",
"scrolled", or "finished", initially "none".NavigateEvent has a navigation handler list, a
list of NavigationInterceptHandler callbacks, initially empty.NavigateEvent has a focus
reset behavior, a NavigationFocusReset-or-null, initially null.NavigateEvent has a scroll
behavior, a NavigationScrollBehavior-or-null, initially null.NavigateEvent has an abort controller, an
NavigateEvent has a classic history API state, a
serialized state or null. It is only used in some cases where the event's navigationType is "push" or "replace", and is set appropriately when the event is
fired.navigationType, destination, canIntercept, userInitiated,
hashChange, signal, formData, downloadRequest, info, and hasUAVisualTransition attributes
must return the values they are initialized to.intercept(options) method steps
are:canIntercept
attribute was initialized to false, then throw a "SecurityError"
this's dispatch flag is unset, then throw an
"InvalidStateError" Assert: this's interception state is either "none" or "intercepted".intercepted".handler"] exists, then append it to this's
navigation handler
list.focusReset"] exists, then:focusReset"], then the user agent may
report a warning to the console indicating that the focusReset option for a previous call
to intercept() was overridden by this new
value, and the previous value will be ignored.focusReset"].scroll"]
exists, then:scroll"], then the user agent may
report a warning to the console indicating that the scroll option for a previous call to
intercept() was overridden by this new value,
and the previous value will be ignored.scroll"].scroll() method steps are:committed", then throw an "InvalidStateError"
Process scroll behavior given this.NavigateEvent event:Document is not fully
active, then throw an "InvalidStateError"
event's "SecurityError"
event's canceled flag is set, then throw an
"InvalidStateError" 7.2.6.9.2 The NavigationDestination interface
[event.destination.urlevent.destination.keykey property of the
destination NavigationHistoryEntry, if this is a "traverse" navigation, or the empty string otherwise. event.destination.idid property of the
destination NavigationHistoryEntry, if this is a "traverse" navigation, or the empty string otherwise. event.destination.indexindex property of
the destination NavigationHistoryEntry, if this is a "traverse" navigation, or −1 otherwise.
event.destination.sameDocumentDocument as the current
one, or not. This will be true, for example, in the case of fragment navigations or history.pushState() navigations.navigateEvent.intercept(), that will not change the
value of this property.event.destination.getState()traverse" navigations, returns the
deserialization of the state stored in the
destination session history entry.push" or "replace" navigations, returns the deserialization of the state passed to navigation.navigate(), if the navigation was initiated
by that method, or undefined it if it wasn't.reload" navigations, returns the deserialization of the state passed to navigation.reload(), if the reload was initiated by that
method, or undefined it if it wasn't.NavigationDestination has a URL, which is a URL.NavigationDestination has an entry, which is a
NavigationHistoryEntry or null.NavigationDestination
corresponds to a "traverse" navigation.NavigationDestination has a state, which is a serialized
state.NavigationDestination has an is same document, which is a
boolean.
url getter steps are to return
this's URL, serialized.key getter steps are:id getter steps are:index getter steps are:sameDocument getter steps are to
return this's is same
document.getState() method steps are to return
StructuredDeserialize(this's state).7.2.6.9.3 Firing the event
navigate event,
through a series of wrapper algorithms given in this section.navigate event at a
Navigation navigation given a session history entry destinationSHE and an optional
user navigation involvement userInvolvement (default "none"):NavigateEvent, in navigation's relevant realm.NavigationDestination
created in navigation's relevant
realm.NavigationHistoryEntry in
navigation's entry list whose session history entry is destinationSHE, or null if no such
NavigationHistoryEntry exists.Document;
otherwise false.navigate event firing algorithm given
navigation, "traverse",
event, destination, userInvolvement, null, and null.navigate event at
a Navigation navigation given a NavigationType navigationType, a URL destinationURL, a boolean isSameDocument, an optional user
navigation involvement userInvolvement (default "none"), an optional entry list-or-null formDataEntryList (default null), an
optional serialized state navigationAPIState (default
StructuredSerializeForStorage(null)), and an optional serialized
state-or-null classicHistoryAPIState (default
null):NavigateEvent, in navigation's relevant realm.NavigationDestination
created in navigation's relevant
realm.navigate event firing algorithm given
navigation, navigationType, event, destination,
userInvolvement, formDataEntryList, and null.navigate event at a
Navigation navigation given a URL destinationURL, a user
navigation involvement userInvolvement, and a string
filename:NavigateEvent, in navigation's relevant realm.NavigationDestination
created in navigation's relevant
realm.navigate event firing algorithm given
navigation, "push", event,
destination, userInvolvement, null, and filename.navigate event firing algorithm
consists of the following steps, given a Navigation navigation, a
NavigationType navigationType, a NavigateEvent
event, a NavigationDestination destination, a user
navigation involvement userInvolvement, an entry list-or-null
formDataEntryList, and a string-or-null downloadRequestFilename:traverseTo(), back(), and forward() will immediately fail when entries and events
are disabled (since there are no entries to traverse to), and if our starting point is instead
navigate() or reload(), then we avoided setting the
upcoming non-traverse API method tracker in the first place.Document.traverse",
then initialize event's canIntercept to true. Otherwise, initialize it to
false.traverse"; or
navigate".navigationType to
navigationType.destination to destination.downloadRequest to
downloadRequestFilename.info to apiMethodTracker's info. Otherwise, initialize it to
undefined.hasUAVisualTransition to true if a visual
transition, to display a cached rendered state of the document's latest
entry, was done by the user agent. Otherwise, initialize it to false.navigation's relevant realm.signal to
event's abort
controller's signal.hashChange to true. Otherwise, initialize it to
false.none", then
initialize event's userInitiated
to true. Otherwise, initialize it to false.formData to a new navigation's relevant realm,
associated to formDataEntryList. Otherwise, initialize it to null.navigate event is null.navigate
event to event.traverse", then consume history-action user
activation.none" or event's destination's is same document is true.none":committed".NavigationTransition created in navigation's relevant realm, whose navigation type is
navigationType, from entry
is fromNHE, and whose finished
promise is a new promise created in navigation's relevant realm.traverse", then set navigation's
suppress normal scroll restoration during ongoing navigation to true.after-transition", then scroll
restoration will happen as part of finishing the
relevant NavigateEvent. Otherwise, there will be no scroll restoration. That is,
no navigation which is intercepted by intercept() goes through the normal scroll
restoration process; scroll restoration for such navigations is either done manually, by the
web developer, or is done after the transition.push" or
"replace", then run the URL and history
update steps given document and event's destination's URL, with serialiedData set to event's classic history API state and
historyHandling set to navigationType.
reload",
then we are converting a reload into a "same-document reload", for which the
URL and history update steps are not appropriate. Navigation API-related stuff
still happens, such as updating the active session
history entry's navigation API state if
this was caused by a call to navigation.reload(),
and all the ongoing navigation tracking.traverse", then this event firing is happening as
part of the traversal process, and that
process will take care of performing the appropriate session history entry updates.navigatesuccess / navigateerror, currententrychange, dispose, apiMethodTracker's promises, and the navigation.transition.finished promise.)
navigate event.navigate event to null.navigatesuccess at navigation.navigate event.navigate event to null.navigateerror at navigation using
ErrorEvent, with error initialized to
rejectionReason, and message, filename, lineno, and colno initialized to appropriate
values that can be extracted from rejectionReason in the same underspecified way
that the report the exception algorithm does.none", then return true.7.2.6.9.4 Scroll and focus behavior
navigateEvent.intercept(), web
developers can suppress the normal scroll and focus behavior for same-document navigations,
instead invoking cross-document navigation-like behavior at a later time. The algorithms in this
section are called at those appropriate later points.NavigateEvent
event, given a boolean didFulfill:intercepted" or "finished".none", then return.finished".NavigateEvent
event:committed" or "scrolled".manual", then
return.after-transition", and continue
onward.Document.NavigateEvent
event:committed" or "scrolled".scrolled", then return.manual", then return.after-transition", and continue
onward.NavigateEvent event:committed".scrolled".navigationType was initialized to "traverse" or "reload", then restore scroll position data
given event's relevant global object's navigable's active session history
entry.Document.7.2.7 Event interfaces
NavigateEvent interface has its own
dedicated section, due to its complexity.7.2.7.1 The
NavigationCurrentEntryChangeEvent interface[event.navigationTypenavigation.updateCurrentEntry().event.fromnavigation.currentEntry, before the current entry
changed.navigationType
is null or "reload", then this value will be the
same as navigation.currentEntry. In that case,
the event signifies that the contents of the entry changed, even if we did not move to a new
entry or replace the current one.navigationType and from attributes must return the
values they were initialized to.7.2.7.2 The
PopStateEvent interfaceFirefox11+Safari6+Chrome16+
Opera?Edge79+
Edge (Legacy)14+Internet ExplorerNo
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android?Firefox4+Safari6+Chrome4+
Opera12.1+Edge79+
Edge (Legacy)12+Internet Explorer10+
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+[event.stateFirefox4+Safari6+Chrome4+
Opera12.1+Edge79+
Edge (Legacy)12+Internet Explorer10+
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+pushState() or replaceState().event.hasUAVisualTransitionstate attribute must return the value it was
initialized to. It represents the context information for the event, or null, if the state
represented is the initial state of the Document.
hasUAVisualTransition attribute must return the value it was initialized to.7.2.7.3 The
HashChangeEvent interfaceFirefox11+Safari6+Chrome16+
Opera?Edge79+
Edge (Legacy)12+Internet ExplorerNo
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android?Firefox3.6+Safari5+Chrome8+
Opera10.6+Edge79+
Edge (Legacy)12+Internet Explorer8+
Firefox Android?Safari iOS5+Chrome Android?WebView Android?Samsung Internet?Opera Android11+[event.oldURLFirefox6+Safari5.1+Chrome8+
Opera12.1+Edge79+
Edge (Legacy)12+Internet ExplorerNo
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+event.newURLFirefox6+Safari5.1+Chrome8+
Opera12.1+Edge79+
Edge (Legacy)12+Internet ExplorerNo
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+oldURL attribute must return the value it was
initialized to. It represents context information for the event, specifically the URL of the
session history entry that was traversed from.newURL attribute must return the value it was
initialized to. It represents context information for the event, specifically the URL of the
session history entry that was traversed to.7.2.7.4 The
PageTransitionEvent interfaceFirefox11+Safari6+Chrome16+
Opera?Edge79+
Edge (Legacy)?Internet ExplorerNo
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android?Firefox1.5+Safari5+Chrome4+
Opera?Edge79+
Edge (Legacy)12+Internet Explorer11
Firefox Android?Safari iOS4+Chrome Android?WebView Android37+Samsung Internet?Opera Android?[event.persistedFirefox11+Safari5+Chrome4+
Opera?Edge79+
Edge (Legacy)12+Internet Explorer11
Firefox Android?Safari iOS4+Chrome Android?WebView Android37+Samsung Internet?Opera Android?pageshow event, returns false if the page is
newly being loaded (and the load event will fire). Otherwise,
returns true.pagehide event, returns false if the page is
going away for the last time. Otherwise, returns true, meaning that the page might be reused if
the user navigates back to this page (if the Document's salvageable state stays true). Document alive in a session
history entry after unloadiframes that are not salvageableAborting a Documentpersisted attribute must return the value
it was initialized to. It represents the context information for the event.Window
window with a boolean persisted, fire
an event named eventName at window, using
PageTransitionEvent, with the persisted attribute initialized to
persisted, the legacy target override flag set.Window object. They are set to true
for historical reasons.7.2.7.5 The
BeforeUnloadEvent interfaceFirefox1.5+Safari7+Chrome30+
Opera?Edge79+
Edge (Legacy)?Internet Explorer4+
Firefox Android?Safari iOS?Chrome Android?WebView Android37+Samsung Internet3.0+Opera Android?[BeforeUnloadEvent-specific initialization methods.BeforeUnloadEvent interface is a legacy interface which allows checking
if unloading is canceled to be controlled not only by canceling the event, but by setting
the returnValue attribute to a value
besides the empty string. Authors should use the method, or other means of canceling
events, instead of using returnValue.returnValue attribute controls the process
of checking if unloading is canceled. When the event is created, the
attribute must be set to the empty string. On getting, it must return the last value it was set
to. On setting, the attribute must be set to the new value.DOMString only for historical reasons.
Any value besides the empty string will be treated as a request to ask the user for
confirmation.