Navigate to an app-absolute path or an external URL.
Path targets must start with / and exclude the deployment basename.
Empty, query-only, and hash-only targets use the current pathname.
An empty target clears query and hash. Path-relative
targets, including . and .., are rejected; use a page routing adapter
for library-relative navigation.
Absolute URLs (including same-origin URLs), protocol-relative URLs, and
schemes such as mailto: are handled by the browser. The replace
option replaces the browser history entry; state is only used for
app-absolute path navigation. Executable URL schemes are replaced with
about:blank and a warning.
Successful app-absolute pushes and replacements update getSnapshot()
and notify subscribers synchronously before returning.
Numeric history traversal may complete asynchronously and is observed
through subscribe. External navigation does not synchronously update
the app location.
Resolve a path to a browser-ready href, including the app's deploy basename.
Executable URL schemes are replaced with about:blank and a warning.
Paths must start with / and exclude the deployment basename. Relative
paths are rejected. Empty, query-only, and hash-only targets, such as ?tab=readme
or #section, use the current pathname.
Absolute URLs, protocol-relative URLs, and schemes such as mailto:
and tel: pass through without the basename, after sanitization.
Only the path portion is inspected, so /search?query=https://example.com
is an ordinary app-absolute target.
Reads the current immutable history snapshot without writing history.
Returns the same object until navigation is published. Reads do not discover browser history writes that have not been reported to subscribers, including silent URL synchronization by plugins.
Each committed navigation publishes a new snapshot, even when its URL and state are unchanged. The nested location retains its identity while its fields are unchanged.
This function has a stable identity and can be called without binding it to the API instance, including as useSyncExternalStore's getSnapshot.
Subscribes to history changes. The snapshot is updated before listeners are called. Successful internal pushes and replacements notify synchronously before navigate returns; traversals may finish asynchronously.
Subscribing does not invoke the listener immediately. Read getSnapshot for the current value. Returns an idempotent unsubscribe function.
This function has a stable identity and can be called without binding it to the API instance, including as useSyncExternalStore's subscribe.
The app's shared navigation and location interface, used by plugins and app chrome. The default implementation owns browser history; apps can provide a custom implementation through an API factory.
The public navigation surface mirrors the
navigate+useHrefpattern used by libraries like react-aria:AppHistoryApi.navigateperforms navigation, and AppHistoryApi.createHref (paired with the publicuseAppHrefhook) resolves an app-absolute path (starting at/, without the deployment basename) to a browser-ready href.