Navigation and route state

Navigate, prefetch, inspect route resolution, and own route subscriptions without leaking browser listeners.

Use anchors first and navigate for imperative transitions

TSX

tsximport { Link, navigate } from "@tavojs/core/router";
import { Button, Stack } from "@tavojs/ui";

export function ProjectNavigation() {
  function openLatestProject() {
    navigate("/projects/latest");
  }

  return (
    <Stack>
      <Link to="/projects">All projects</Link>
      <Button onClick={openLatestProject}>
        Open latest project
      </Button>
    </Stack>
  );
}

Link renders a real anchor, supports keyboard and assistive technology behavior, and marks the active route with aria-current.
Same-origin, unmodified primary clicks become client navigation. External links, downloads, modified clicks, new-window targets, and same-page hashes retain native browser behavior.
navigate(to, { replace, scroll }) is for event-driven transitions. replace defaults to false and scroll defaults to true.
Back and forward navigation follows browser history and restores recorded scroll positions.

Read route status as a state machine

tsimport {
  getRouteStatus,
  subscribeRouteStatus,
} from "@tavojs/core/router";

console.debug(getRouteStatus("/reports").status);

const stop = subscribeRouteStatus((status) => {
  document.documentElement.dataset.routeStatus = status.status;
}, "/reports");

// Return stop from the lifecycle owner.

Status	Meaning
`idle`	No active or reusable resolution is recorded for the path.
`loading`	An active navigation is running middleware and loaders.
`prefetching`	Background resolution is running without changing history.
`ready`	A resolved result is available for the path.
`redirecting`	Middleware or route resolution selected another location.
`error`	Resolution failed; inspect the status error for reporting.

Each record follows RouteStatus. Read a path with getRouteStatus(pathname) and observe future transitions with subscribeRouteStatus(listener, pathname?).

getCurrentPathname() reads the current browser path.
getAvailableRoutes() returns discovered PageRouteDefinition records; the catalog is not an authorization boundary.
getResolvedRoute(pathname) returns the current resolved route snapshot when available. Pass the path explicitly when inspecting anything other than the active route. The renderer-state shape is intentionally not a separately importable route-author contract.

Read once, subscribe, and return cleanup

subscribePathname, subscribeAvailableRoutes, and subscribeRouteStatus publish future changes; they do not replace the initial synchronous read. A createTavo controller is a natural owner because onMount can return one cleanup that releases every subscription.

TSX

tsximport {
  createTavo,
  TavoController
} from "@tavojs/core";
import {
  getCurrentPathname,
  getRouteStatus,
  subscribePathname,
  subscribeRouteStatus,
  type RouteStatus
} from "@tavojs/core/router";
import { Text } from "@tavojs/ui";

type RouteProgressState = {
  pathname: string;
  status: RouteStatus["status"];
};

class RouteProgressController extends TavoController {
  sync(pathname = getCurrentPathname()) {
    this.model.patch({
      pathname,
      status: getRouteStatus(pathname).status
    });
  }

  onMount() {
    this.sync();
    const stopPathname = subscribePathname((pathname) => {
      this.sync(pathname);
    });
    const stopStatus = subscribeRouteStatus((status) => {
      this.model.patch({
        pathname: status.pathname,
        status: status.status
      });
    });

    return function cleanupRouteProgress() {
      stopPathname();
      stopStatus();
    };
  }
}

export const RouteProgress = createTavo<
  Record<string, never>,
  RouteProgressState,
  RouteProgressController
>({
  model: () => ({
    pathname: "/",
    status: "idle"
  }),
  controller: RouteProgressController,
  view: ({ state }) => {
    return (
      <Text aria-live="polite">
        {state.pathname}: {state.status}
      </Text>
    );
  }
});

Prefetch without navigating

TSX

tsximport { Link, prefetchRoute } from "@tavojs/core/router";

export function ProjectLink({ id }: { id: string }) {
  const pathname = `/projects/${id}`;
  let prefetch: AbortController | null = null;

  function startPrefetch() {
    prefetch?.abort();
    prefetch = new AbortController();
    void prefetchRoute(pathname, {
      signal: prefetch.signal
    });
  }

  function stopPrefetch() {
    prefetch?.abort();
    prefetch = null;
  }

  return (
    <span
      onMouseEnter={startPrefetch}
      onMouseLeave={stopPrefetch}
      onFocus={startPrefetch}
      onBlur={stopPrefetch}
    >
      <Link to={pathname}>
        Open project {id}
      </Link>
    </span>
  );
}

prefetchRoute runs the target's client-eligible middleware and loaders but does not change history or render the target pending component.
Status moves through prefetching and then ready or error. Cancellation returns the prefetch to idle.
Pass an AbortSignal when hover, focus, a controller, or another owner can stop needing the result.
Prefetch is an optimization. Navigation must still work when no prefetch ran, failed, or was evicted.

Verify navigation and cancellation

Replace a slow navigation with a second destination and confirm the obsolete result never becomes active.
Abort a hover prefetch and confirm it neither changes the URL nor displays pending UI.
Mount and unmount subscription-owning components repeatedly while checking that each cleanup runs.
Test Link with keyboard activation, modifier keys, downloads, external URLs, hashes, and browser back/forward.

BASH

bashnpx tavo routes
npx tavo inspect route /projects/example --json

Look up exact public types

Follow linked API names to their canonical TypeScript declarations and package boundaries.