This document describes an API that gives web authors additional control over
user agent's restoration of persisted user state in particular the document's
scroll position.
*NOTE*: The proposed API is now part of [WhatWG HTML Living
Standard](https://html.spec.whatwg.org/multipage/browsers.html#dom-history-scroll-restoration)
We actively solicit comments on this document either via emailing to
[whatwg@whatwg.org mailing list][whatwg-mailinglist] or opening an issue
on [GitHub][github-repo] for this repository.
## Design
We propose to modify History API and make it possible for web authors to
explicitly disable the default scroll restoration behavior. This is achieved
by adding a new attribute, `scrollRestoration`, to `window.history`.
This new attribute can take two values: 'auto', 'manual' with 'auto' being the
default.
Setting `scrollRestoration` to a new value updates the [current entry
][current-entry-def] in history session. Also any future entry that is added
to history session for the same document will use this new `scrollRestoration`
value. However, changing this value does not impact any previous entries in
sessions history including those that belong to the same document.
Furthermore, any navigation to a new page with a different document resets the
`scrollRestoration` to its default value.
Note that this ensures that changes to `scrollRestoration` only affect entries that
will be created for the same document (e.g., entries created using pushState,
or due to fragment navigation).
### Child Frames
Disabling scroll restoration in one frame should not impact the
scroll restoration for any other frame including any of its child frames.
### Web IDL
enum ScrollRestoration { "auto", "manual" };
partial interface History {
attribute ScrollRestoration scrollRestoration;
};
- scrollRestoration
-
Indicates whether the user agent should restore scroll position when
traversing to this entry. Anytime this attribute is modified the current
entry in joint session history should be updated to reflect the change.
## Spec Changes
### History traversal
Modify the [history traversal algorithm][history-traverse-algorithm], add the
following new section to the spec defining persisted user state restoration
process and update steps 3 and 9 as following:
9\. If the specified entry has persisted user state, and the user agent wants
to update aspects of the document and its rendering **it should run the
`persisted user state restoration` steps.**
#### Persisted user state restoration
Run the following steps immediately:
1. If the entry has an scroll restoration value, let *scrollRestoration* be that.
2. If *scrollRestoration* is 'manual' the user agent should not
restore the scroll position for the document otherwise it may.
3. Set `history.scrollRestoration` to *scrollRestoration*
4. User agent may now update other aspects of the document and its
rendering, for instance values of form fields, that it had previously
recorded.
### Push State
Modify the [pushState algorithm][pushstate-algorithm] and update a step 4.3 as following:
(4\.)3\. If appropriate, update the current entry to reflect any state that
the user agent wishes to persist, **and current history scroll restoration
value**. The entry is then said to be an entry with persisted user state.
### Navigating to Fragment
Modify the [navigating to a fragment identifier algorithm][scroll-to-frag-algorithm]
and update step 3 as following:
3\. Append a new entry at the end of the History object representing the new
resource and its Document object, related state, **and current history
scroll restoration value**. Its URL must be set to the address to which the
user agent was navigating. The title must be left unset.
### Navigating to a new page
Modify the [update the session history with the new page][update-session-algorithm]
algorithm and update step 2.2 as following:
(2\.)2\. Append a new entry at the end of the History object representing
the new resource and its Document object and related state **and with default
history scroll restoration value i.e. "auto"**.
[whatwg-mailinglist]: https://lists.w3.org/Archives/Public/public-whatwg-archive/
[github-repo]: https://github.com/majido/scroll-restoration-proposal
[background]: https://docs.google.com/document/d/1Tiu8PjvBtNOAgeh6yrs7bOrXxQcavQLiNtRJ_ToLlVM/edit
[history-traverse-algorithm]: https://html.spec.whatwg.org/#history-traversal
[pushstate-algorithm]: https://html.spec.whatwg.org/#dom-history-pushstate
[scroll-to-frag-algorithm]: https://html.spec.whatwg.org/#scroll-to-fragid
[update-session-algorithm]: https://html.spec.whatwg.org/#update-the-session-history-with-the-new-page
[current-entry-def]: https://html.spec.whatwg.org/#current-entry