Snapshots

Ephemeral DOM state — like scroll positions on sidebars, the content of <input> elements and so on — is discarded when you navigate from one page to another.

For example, if the user fills out a form but navigates away and then back before submitting, or if the user refreshes the page, the values they filled in will be lost. In cases where it's valuable to preserve that input, you can take a snapshot of DOM state, which can then be restored if the user navigates back.

To do this, call snapshot from $app/navigation during component initialization:

<script>
	import { snapshot } from '$app/navigation';

	let comment = $state('');

	snapshot({
		capture: () => comment,
		restore: (value) => (comment = value)
	});
</script>

<form method="POST">
	<label for="comment">Comment</label>
	<textarea id="comment" bind:value={comment} />
	<button>Post comment</button>
</form>

When you navigate away from this page — including via shallow routing — the capture function is called immediately before the page updates, and the returned value is associated with the current entry in the browser's history stack. If you navigate back, the restore function is called with the stored value as soon as the page is updated.

Snapshots must have a unique ID in order to survive across component remounts and page reloads. By default, this is generated from the stack trace when snapshot(...) is called, but you can also explicitly provide an id to (for example) keep snapshots stable across deployments, even if the stack trace differs because of changes to the source code, or to distinguish snapshots created via a shared wrapper function or in multiple instances of the same component:

snapshot({
	id: 'comment',
	capture: () => comment,
	restore: (value) => (comment = value)
});

The optional reset callback runs on navigations where there is no captured value to restore, such as when a new history entry is created.

Captured values are serialized with devalue, which handles JSON, objects such as Date and Map, and custom types specified in your transport hook. The serialized data is persisted to sessionStorage, which allows the state to be restored when the page is reloaded, or when the user navigates back from a different site.

export const snapshot

<script>
	let comment = $state('');

	/** @type {import('./$types').Snapshot<string>} */
	export const snapshot = {
		capture: () => comment,
		restore: (value) => comment = value
	};
</script>

Values captured this way are serialized as JSON, and shallow navigations do not capture them.