History

Navigate the stack

GoBack / GoForward / Go

Move through the session history exactly like the browser's Back and Forward buttons. Go accepts a relative delta; navigating past either end of the stack is a silent no-op.

await history.GoBack();      // same as the Back button
await history.GoForward();   // same as the Forward button

await history.Go(-2);        // two entries back
await history.Go();          // no delta: reloads the current page

Live sample

navigation output

Results will appear here when you interact with the samples.

Length and state

GetLength / GetState / GetState<T>

GetLength reports how many entries the session history holds, including the current page. GetState returns the state object attached to the active entry, with a generic overload for strongly-typed deserialization.

int length = await history.GetLength();

object state = await history.GetState();

var typed = await history.GetState<MyState>();

public record MyState(int Step, string Name);

Live sample

length and state output

Results will appear here when you interact with the samples.

Push and replace entries

PushState / ReplaceState

PushState adds a new history entry with an optional state object and same-origin URL, without reloading the page. ReplaceState swaps the current entry in place - the standard tool for keeping the address bar in sync with client-side UI state.

await history.PushState(new { step = 2 }, "history?step=2");

await history.ReplaceState(new { step = 2, revised = true }, "history?step=2b");

// pressing Back now raises popstate with the previous state object

Live sample

Watch the address bar - both calls change the URL without a page load.

push and replace output

Results will appear here when you interact with the samples.

React to popstate

AddPopState / SubscribePopState / RemovePopState / RemoveAllPopStates

popstate fires whenever the active history entry changes through user navigation (Back, Forward or Go), delivering the state object of the entry that became active. SubscribePopState returns a disposable subscription; AddPopState returns a Guid you can pass to RemovePopState.

ButilSubscription sub = await history.SubscribePopState(
    state => Console.WriteLine($"popped: {state}"));

// alternative, id-based lifecycle:
Guid id = await history.AddPopState(state => { /* ... */ });
await history.RemovePopState(id);

// or drop everything this instance registered:
await history.RemoveAllPopStates();

Live sample

Subscribe, push a couple of entries above, then use the browser Back button.

popstate output

Results will appear here when you interact with the samples.

Scroll restoration

GetScrollRestoration / SetScrollRestoration

Controls whether the browser restores the scroll position automatically when the user navigates through history. Set it to Manual when your app manages scroll itself, for example in virtualized lists.

ScrollRestoration current = await history.GetScrollRestoration();

await history.SetScrollRestoration(ScrollRestoration.Manual);
await history.SetScrollRestoration(ScrollRestoration.Auto);

Live sample

scroll restoration output

Results will appear here when you interact with the samples.

Navigation leaves this pageGoBack, GoForward and Go perform real history navigations - the demo buttons above can move you away from this page (use the browser's Forward button to return). Go(0) or Go() reloads the current page entirely.

Same-origin URLs only The URL passed to PushState and ReplaceState must be same-origin with the current page, otherwise the browser throws a security exception. The state object must be serializable.

API reference

Member

Signature

Description

GetLength

Task<int> GetLength()

Number of entries in the session history, including the current page.

GetScrollRestoration

Task<ScrollRestoration> GetScrollRestoration()

Current scroll restoration behavior (Auto or Manual).

SetScrollRestoration

Task SetScrollRestoration(ScrollRestoration value)

Sets the default scroll restoration behavior for history navigation.

GetState

Task<object> GetState()

The state object at the top of the history stack.

GetState<T>

Task<T?> GetState<T>()

Strongly-typed accessor for the current state object.

GoBack

Task GoBack()

Goes to the previous page in session history; no-op beyond the first entry.

GoForward

Task GoForward()

Goes to the next page in session history; no-op beyond the most recent entry.

Task Go(int? delta = null)

Loads the entry at a relative offset; null or 0 reloads the current page.

PushState

Task PushState(object? state = null, string? url = null)

Pushes a new entry with the given state and same-origin URL onto the stack.

ReplaceState

Task ReplaceState(object? state = null, string? url = null)

Replaces the current entry's state and, optionally, its URL.

AddPopState

ValueTask<Guid> AddPopState(Action<object> handler)

Registers a popstate handler; returns an id for RemovePopState.

SubscribePopState

ValueTask<ButilSubscription> SubscribePopState(Action<object> handler)

popstate subscription returning a disposable handle.

RemovePopState

ValueTask RemovePopState(Guid id)

Removes a popstate handler by id. An overload accepts the handler delegate and returns the removed ids (ValueTask<Guid[]>).

RemoveAllPopStates

ValueTask RemoveAllPopStates()

Removes every popstate handler registered through this instance.

DisposeAsync

ValueTask DisposeAsync()

Removes all popstate handlers and releases the interop reference. InvokeHistoryPopState is the public JSInvokable dispatch bridge and is not intended for app code.