Edition for Web Developers — Last Updated 3 June 2023
Window
objectSupport in all current engines.
window.window
window.frames
window.self
These attributes all return window.
window.document
Returns the Document
associated with window.
document.defaultView
Returns the Window
associated with document, if there is one, or null otherwise.
window = window.open([ url [, target [, features ] ] ])
Opens a window to show url (defaults to "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
"These behave equivalently to the noopener
and noreferrer
link types on hyperlinks.
popup
"Encourages user agents to provide a minimal web browser user interface for the new
window. (Impacts the visible
getter on all
BarProp
objects as well.)
globalThis. open( "https://email.example/message/CAOOOkFcWW97r8yg=SsWg7GgCmp4suVX9o85y8BvNRqMjuc5PXg" , undefined , "noopener,popup" );
window.name [ = value ]
Returns the name of the window.
Can be set, to change the name.
window.close()
Closes the window.
window.closed
Returns true if the window has been closed, false otherwise.
window.stop()
Cancels the document load.
Window
objectwindow.length
Returns the number of document-tree child navigables.
window[index]
Returns the WindowProxy
corresponding to the indicated document-tree child navigables.
Window
objectwindow[name]
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 document.getElementById()
or document.querySelector()
.
window.top
Returns the WindowProxy
for the top-level traversable.
window.opener [ = value ]
Returns the WindowProxy
for the opener browsing context.
Returns null if there isn't one or if it has been set to null.
Can be set to null.
window.parent
Returns the WindowProxy
for the parent
navigable.
window.frameElement
Returns the navigable container element.
Returns null if there isn't one, and in cross-origin situations.
For historical reasons, the Window
interface had some properties that represented
the visibility of certain web browser interface elements.
For privacy and interoperability reasons, those properties now return all return the same value: whether or not the window represents a popup window.
window.locationbar.visible
Support in all current engines.
window.
.visiblewindow.personalbar.visible
window.scrollbars.visible
window.statusbar.visible
window.toolbar.visible
Returns true if the Window
is not a popup; otherwise, returns false.
WindowProxy
exotic objectA WindowProxy
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.
Location
interfaceSupport in all current engines.
Support in all current engines.
Support in all current engines.
Each Window
object is associated with a unique instance of a Location
object, allocated when the Window
object is created.
document.location [ = value ]
window.location [ = value ]
Returns a Location
object with the current page's location.
Can be set, to navigate to another page.
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.href
Returns the Location
object's URL.
Can be set, to navigate to the given URL.
location.origin
Returns the Location
object's URL's origin.
location.protocol
Returns the Location
object's URL's scheme.
Can be set, to navigate to the same URL with a changed scheme.
location.host
Returns the Location
object's URL's host and port (if different from the default
port for the scheme).
Can be set, to navigate to the same URL with a changed host and port.
location.hostname
Returns the Location
object's URL's host.
Can be set, to navigate to the same URL with a changed host.
location.port
Returns the Location
object's URL's port.
Can be set, to navigate to the same URL with a changed port.
location.pathname
Returns the Location
object's URL's path.
Can be set, to navigate to the same URL with a changed path.
location.search
Returns the Location
object's URL's query (includes leading "?
" if non-empty).
Can be set, to navigate to the same URL with a changed query (ignores leading "?
").
location.hash
Returns the Location
object's URL's fragment (includes leading "#
" if non-empty).
Can be set, to navigate to the same URL with a changed fragment (ignores leading "#
").
location.assign(url)
Navigates to the given URL.
location.replace(url)
Removes the current page from the session history and navigates to the given URL.
location.reload()
Reloads the current page.
location.ancestorOrigins
Returns a DOMStringList
object listing the origins of the ancestor navigables' active documents.
History
interfaceSupport in all current engines.
Support in all current engines.
history.length
Returns the number of overall session history entries for the current traversable navigable.
history.scrollRestoration
Returns the scroll restoration mode of the active session history entry.
history.scrollRestoration = value
Set the scroll restoration mode of the active session history entry to value.
history.state
Returns the serialized state of the active session history entry, deserialized into a JavaScript value.
history.go()
Reloads the current page.
history.go(delta)
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.
history.back()
Goes back one step in the overall session history entries list for the current traversable navigable.
If there is no previous page, does nothing.
history.forward()
Goes forward one step in the overall session history entries list for the current traversable navigable.
If there is no next page, does nothing.
history.pushState(data, "")
Adds a new entry into session history with its serialized 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.)
history.pushState(data, "", url)
Adds a new entry into session history with its serialized state set to a serialization of data, and with its URL set to url.
If the current Document
cannot have
its URL rewritten to url, a "SecurityError
"
DOMException
will be thrown.
(The second parameter exists for historical reasons, and cannot be omitted; passing the empty string is traditional.)
history.replaceState(data, "")
Updates the serialized 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.)
history.replaceState(data, "", url)
Updates the serialized state of the active session history entry to a structured clone of data, and its URL to url.
If the current Document
cannot have
its URL rewritten to url, a "SecurityError
"
DOMException
will be thrown.
(The second parameter exists for historical reasons, and cannot be omitted; passing the empty string is traditional.)
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:pass@example.com/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
| ❌ |
Note how only the URL of the Document
matters, and not its origin. They can mismatch in
cases like about:blank
Document
s with inherited origins, in sandboxed
iframe
s, or when the document.domain
setter has been used.
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:
<!DOCTYPE HTML>
<!-- this is https://example.com/line?x=5 -->
< html lang = "en" >
< title > Line Game - 5</ title >
< p > You are at coordinate 5 on the line.</ p >
< p >
< a href = "?x=6" > Advance to 6</ a > or
< a href = "?x=4" > retreat to 4</ a > ?
</ p >
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:
<!DOCTYPE HTML>
<!-- this starts off as https://example.com/line?x=5 -->
< html lang = "en" >
< title > Line Game - 5</ title >
< p > You are at coordinate < span id = "coord" > 5</ span > on the line.</ p >
< p >
< a href = "?x=6" onclick = "go(1); return false;" > Advance to 6</ a > or
< a href = "?x=4" onclick = "go(-1); return false;" > retreat to 4</ a > ?
</ p >
< script >
var currentPage = 5 ; // prefilled by server
function go( d) {
setupPage( currentPage + d);
history. pushState( currentPage, "" , '?x=' + currentPage);
}
onpopstate = function ( event) {
setupPage( event. state);
}
function setupPage( page) {
currentPage = page;
document. title = 'Line Game - ' + currentPage;
document. getElementById( 'coord' ). textContent = currentPage;
document. links[ 0 ]. href = '?x=' + ( currentPage+ 1 );
document. links[ 0 ]. textContent = 'Advance to ' + ( currentPage+ 1 );
document. links[ 1 ]. href = '?x=' + ( currentPage- 1 );
document. links[ 1 ]. textContent = 'retreat to ' + ( currentPage- 1 );
}
</ 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 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.
Most applications want to use the same scroll restoration mode value for all of
their history entries. To achieve this they can set the 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.
< head >
< script >
if ( 'scrollRestoration' in history)
history. scrollRestoration = 'manual' ;
</ script >
</ head >
PopStateEvent
interfaceSupport in all current engines.
Support in all current engines.
event.state
Returns a copy of the information that was provided to pushState()
or replaceState()
.
HashChangeEvent
interfaceHashChangeEvent/HashChangeEvent
Support in all current engines.
Support in all current engines.
event.oldURL
Returns the URL of the session history entry that was previously current.
event.newURL
Returns the URL of the session history entry that is now current.
PageTransitionEvent
interfacePageTransitionEvent/PageTransitionEvent
Support in all current engines.
Support in all current engines.
event.persisted
For the pageshow
event, returns false if the page is
newly being loaded (and the load
event will fire). Otherwise,
returns true.
For the 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).
Things that can cause the page to be unsalvageable include:
Document
alive in a session
history entry after unloadiframe
s that are not salvageableWebSocket
objectsDocument
BeforeUnloadEvent
interfaceSupport in all current engines.
There are no BeforeUnloadEvent
-specific initialization methods.
The BeforeUnloadEvent
interface is a legacy interface which allows checking
if unloading is user-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 preventDefault()
method, or other means of canceling
events, instead of using returnValue
.