use-navigation-api

Reactive access to the Navigation API (window.navigation).


Package	`@vizejs/composable/use-navigation-api`
Own the source	`vize lib pull composable:use-navigation-api`
Runtime exports	`useNavigationApi`
Gzip budget	3072 B

Minimal setup

Use a Vue 3.5+ project with Vue SFC compilation configured (see Vite+ integration).

vp install @vizejs/composable

Import the entry directly. Call lifecycle-bound utilities inside <script setup> so cleanup follows the component scope; consult the runtime contract for this entry's SSR and hydration behavior.

import { useNavigationApi } from "@vizejs/composable/use-navigation-api";

Try it

Make wizard steps real history entries

Push same-document navigations with state so Back and Forward move through steps.

Open the interactive example

What to observe: Go to step 2 and step 3 add history entries; Back returns to step 2.

parseState validates the stored state. Use navigate listeners to intercept navigations in single-page apps.

Compare the initial and interacted states

Make wizard steps real history entries: initial state — Initial state

Make wizard steps real history entries: state after the verified interactions — After the verified interactions

Copy the example

Save this complete SFC in your Vue project. Its public imports and source are the same ones executed in the preview.

<script setup lang="ts">
import { useMounted } from "@vizejs/composable/use-mounted";
import { useNavigationApi } from "@vizejs/composable/use-navigation-api";

const { supported, currentEntry, canGoBack, navigate, back } = useNavigationApi<{ step: number }>({
  parseState: (raw) =>
    typeof raw === "object" && raw !== null && typeof (raw as { step?: unknown }).step === "number"
      ? (raw as { step: number })
      : undefined,
});

const mounted = useMounted();

function goToStep(step: number) {
  void navigate(`#step-${step}`, { state: { step } });
}
</script>

<template>
  <div class="composable-example">
    <p>Move through wizard steps as real history entries, so Back works as expected.</p>
    <div class="example-actions">
      <button type="button" @click="() => goToStep(2)">Go to step 2</button>
      <button type="button" @click="() => goToStep(3)">Go to step 3</button>
      <button type="button" :disabled="!canGoBack" @click="() => back()">Back</button>
    </div>
    <output aria-live="polite">{{
      !mounted
        ? "Reading history…"
        : supported
          ? `Current entry: ${currentEntry?.url?.split("#")[1] ?? "start"}`
          : "The Navigation API is not available."
    }}</output>
  </div>
</template>

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`useNavigationApi`	system	experimental	deterministic-fallback	caller-managed	caller, reactive-scope	web, desktop	`URL`, `window`	`tryOnScopeDispose`

API

`useNavigationApi`

Reactive access to the Navigation API (window.navigation). Entry snapshots refresh on currententrychange, navigatesuccess and navigateerror. Actions resolve to a NavigationOutcome and never reject; failures also land in error. Listeners (including interceptors) are removed when the owning reactive scope stops; outside a scope the caller removes them with the returned functions. Server rendering: nothing is read or subscribed; supported is false, currentEntry null, entries empty, and actions resolve to { status: "unsupported" }. Inside a component the host is resolved after mounting, so hydration renders this server state first.

function useNavigationApi<State = unknown>( options: UseNavigationApiOptions<State> = {}, ): NavigationApiControls<State>

const nav = useNavigationApi<{ tab: string }>();
nav.intercept((url) => url.pathname.startsWith("/app/"), {
  handler: async () => renderRoute(location.pathname),
});

Types

`NavigationHistoryEntryLike`

Minimal NavigationHistoryEntry.

Member	Type	Description
`url`	`string \| null`	Entry URL, or null when hidden (cross-origin).
`key`	`string`	Key identifying the history slot.
`id`	`string`	Unique identifier of the entry.
`index`	`number`	Index in the entry list, or -1.
`sameDocument`	`boolean`	Whether the entry belongs to the current document.
`getState`	`() => unknown`	Developer-defined state.

`NavigationDestinationLike`

Minimal NavigationDestination.

Member	Type	Description
`url`	`string`	Destination URL.
`index`	`number`	Index of the destination entry for traversals, otherwise -1.
`sameDocument`	`boolean`	Whether the destination is the current document.
`getState`	`() => unknown`	State of the destination.

`NavigationInterceptInit`

Options accepted by NavigateEventLike.intercept.

Member	Type	Description
`handler`?	`() => Promise<void>`	Performs the same-document navigation.
`focusReset`?	`"after-transition" \| "manual"`	Focus behavior after the navigation.
`scroll`?	`"after-transition" \| "manual"`	Scroll behavior after the navigation.

`NavigateEventLike`

Minimal NavigateEvent.

Member	Type	Description
`navigationType`	`NavigationTypeName`	Navigation type.
`destination`	`NavigationDestinationLike`	Where the navigation goes.
`canIntercept`	`boolean`	Whether `intercept` may be called.
`userInitiated`	`boolean`	Whether the user initiated the navigation.
`hashChange`	`boolean`	Whether only the fragment changes.
`downloadRequest`	`string \| null`	Download file name for `<a download>` navigations, else null.
`signal`	`AbortSignal`	Aborted when the navigation is cancelled.
`info`	`unknown`	Info passed by the initiator.
`intercept`	`(options?: NavigationInterceptInit) => void`	Convert the navigation into a same-document navigation.
`preventDefault`	`() => void`	Cancel the navigation when cancelable.

`NavigationResultLike`

Minimal result of a Navigation API action.

Member	Type	Description
`committed`?	`Promise<NavigationHistoryEntryLike>`	Resolves when the URL and entry changed.
`finished`?	`Promise<NavigationHistoryEntryLike>`	Resolves when the navigation finished (handlers settled).

`NavigationHost`

Minimal window.navigation.

Member	Type	Description
`currentEntry`	`NavigationHistoryEntryLike \| null`	Current entry.
`transition`	`{ /** Navigation type. / readonly navigationType: NavigationTypeName; /* Entry navigated away from. */ readonly from: NavigationHistoryEntryLike; } \| null`	Ongoing intercepted navigation.
`canGoBack`	`boolean`	Whether `back` is possible.
`canGoForward`	`boolean`	Whether `forward` is possible.
`entries`	`() => readonly NavigationHistoryEntryLike[]`	Same-origin entries of the session history.
`navigate`	`(url: string, options?: { state?: unknown; history?: NavigationHistoryMode; info?: unknown }) => NavigationResultLike`	Navigate to `url`.
`back`	`(options?: { info?: unknown }) => NavigationResultLike`	Traverse one entry back.
`forward`	`(options?: { info?: unknown }) => NavigationResultLike`	Traverse one entry forward.
`traverseTo`	`(key: string, options?: { info?: unknown }) => NavigationResultLike`	Traverse to the entry with `key`.
`reload`	`(options?: { state?: unknown; info?: unknown }) => NavigationResultLike`	Reload the current entry.
`updateCurrentEntry`	`(options: { state: unknown }) => void`	Replace the current entry's state without navigating.
`addEventListener`	`(type: NavigationEventName, listener: (event: Event) => void) => void`	Subscribe to a navigation event.
`removeEventListener`	`(type: NavigationEventName, listener: (event: Event) => void) => void`	Unsubscribe from a navigation event.

`NavigationEntrySnapshot`

Plain snapshot of a history entry.

Member	Type	Description
`url`	`string \| null`	Entry URL, or null when hidden.
`key`	`string`	Key identifying the history slot.
`id`	`string`	Unique identifier of the entry.
`index`	`number`	Index in the entry list.
`sameDocument`	`boolean`	Whether the entry belongs to the current document.

`NavigationTransitionSnapshot`

Plain snapshot of the ongoing navigation.

Member	Type	Description
`navigationType`	`NavigationTypeName`	Navigation type.
`from`	`NavigationEntrySnapshot`	Entry navigated away from.

`NavigationEntryChange`

Details passed to onCurrentEntryChange listeners.

Member	Type	Description
`navigationType`	`NavigationTypeName \| null`	Navigation type, or null for `updateCurrentEntry`.
`from`	`NavigationEntrySnapshot`	Previous entry.

`NavigationNavigateOptions`

Options of NavigationApiControls.navigate.

Member	Type	Description
`state`?	`State`	State stored on the new entry.
`history`?	`NavigationHistoryMode`	History handling.
`info`?	`unknown`	Info handed to `navigate` listeners.

`NavigationInterceptOptions`

Options of NavigationApiControls.intercept.

Member	Type	Description
`handler`?	`(event: NavigateEventLike) => Promise<void> \| void`	Runs the same-document navigation.
`focusReset`?	`"after-transition" \| "manual"`	Focus behavior after the navigation.
`scroll`?	`"after-transition" \| "manual"`	Scroll behavior after the navigation.

`UseNavigationApiOptions`

Options for useNavigationApi.

Member	Type	Description
`navigation`?	`MaybeRefOrGetter<NavigationHost \| null \| undefined>`	Navigation API capability for alternate runtimes and tests.
`parseState`?	`(raw: unknown) => State \| undefined`	Validate or convert raw entry state into `State`; return undefined for foreign state.

`NavigationApiControls`

Reactive state and actions returned by useNavigationApi.

Member	Type	Description
`supported`	`ComputedRef<boolean>`	Whether the Navigation API is available.
`currentEntry`	`Readonly<ShallowRef<NavigationEntrySnapshot \| null>>`	Snapshot of the current entry.
`entries`	`Readonly<ShallowRef<readonly NavigationEntrySnapshot[]>>`	Snapshots of the same-origin session entries.
`canGoBack`	`Readonly<ShallowRef<boolean>>`	Whether `back` is possible.
`canGoForward`	`Readonly<ShallowRef<boolean>>`	Whether `forward` is possible.
`transition`	`Readonly<ShallowRef<NavigationTransitionSnapshot \| null>>`	Ongoing intercepted navigation.
`state`	`ComputedRef<State \| undefined>`	State of the current entry (not proxied), refreshed with the entry.
`error`	`Readonly<ShallowRef<unknown>>`	Most recent failed action or `navigateerror`, cleared on success.
`getState`	`() => State \| undefined`	Read the current entry's state now.
`onNavigate`	`(listener: (event: NavigateEventLike) => void) => () => void`	Listen to `navigate`.
`onNavigateSuccess`	`(listener: () => void) => () => void`	Listen to `navigatesuccess`.
`onNavigateError`	`(listener: (error: unknown) => void) => () => void`	Listen to `navigateerror`.
`onCurrentEntryChange`	`(listener: (change: NavigationEntryChange) => void) => () => void`	Listen to `currententrychange`.
`intercept`	`( predicate: (url: URL, event: NavigateEventLike) => boolean, options?: NavigationInterceptOptions, ) => () => void`	Intercept interceptable, same-origin, non-download, non-hash navigations whose destination matches `predicate`.
`navigate`	`( url: string, options?: NavigationNavigateOptions<State>, ) => Promise<NavigationOutcome>`	Navigate to `url`.
`back`	`(info?: unknown) => Promise<NavigationOutcome>`	Go back one entry.
`forward`	`(info?: unknown) => Promise<NavigationOutcome>`	Go forward one entry.
`traverseTo`	`(key: string, info?: unknown) => Promise<NavigationOutcome>`	Traverse to the entry with `key`.
`reload`	`(options?: { readonly state?: State; readonly info?: unknown; }) => Promise<NavigationOutcome>`	Reload the current entry, optionally replacing its state.
`updateCurrentEntry`	`(options: { readonly state: State }) => boolean`	Replace the current entry's state without navigating.