Routing and navigation

Auto Pages discovers application routes from src/pages and owns matching, layouts, loaders, route pending and error views, metadata, focus restoration, accessibility announcements, and scroll restoration. Route folders, dynamic segments, groups, 404 pages, and error pages all participate in the same generated route graph.

The Core Link performs SPA navigation and sets aria-current on the active destination. New routes begin at the top, hashes scroll into view, and browser back or forward restores saved positions.

tsximport { Link } from "@tavojs/core/router";
import { Inline } from "@tavojs/ui";

export function AccountNavigation() {
  return <Inline as="nav" aria-label="Account">
    <Link to="/account/profile">Profile</Link>
    <Link to="/account/security" scroll={false}>Security</Link>
  </Inline>;
}

Prefetch routes when intent is clear, such as pointer hover or focus on a high-probability destination. Prefetching resolves work without changing the URL or rendering the target page's pending component. Route status APIs let interface code show loading, prefetching, ready, or error states without duplicating the router state machine.

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

export async function prepareReports() {
  await prefetchRoute("/reports");
  return getRouteStatus("/reports");
}

Auto Pages exposes synchronous route state and disposable subscriptions from @tavojs/core/router. Development inspection lives under @tavojs/core/dev, while tavo routes and tavo inspect route show the generated graph without adding application code.

• Use getResolvedRoute and getRouteStatus for current resolution state.

• Use subscribeAvailableRoutes and subscribeRouteStatus when interface state must react to route changes.

• Run tavo routes, tavo inspect route <path> --json, or import getAutoPagesInspection from @tavojs/core/dev during development.

tsimport {
  getAvailableRoutes,
  getCurrentPathname,
  subscribePathname
} from "@tavojs/core/router";

console.log(getCurrentPathname(), getAvailableRoutes());

const unsubscribe = subscribePathname((pathname) => {
  console.log("Route changed:", pathname);
});

// Call when this observer's owner is disposed.
unsubscribe();

Auto Pages discovers application routes from src/pages. Import its navigation and route-state APIs from @tavojs/core/router. Reads are synchronous; subscribe functions return an unsubscribe callback; prefetchRoute resolves route middleware and loaders without changing browser history.

• Route status is idle, loading, prefetching, ready, redirecting, or error.

• A page pending export is visible only during active client-side route resolution; prefetchRoute never renders it.

• Without an active resolver, prefetchRoute leaves the route idle rather than throwing.

• Pass an AbortSignal when hover, focus, or another owner should be able to cancel a prefetch.

• Call every returned unsubscribe function when its component, controller, or external owner is disposed.

• Import getAutoPagesInspection from @tavojs/core/dev for development inspection, or use tavo routes and tavo inspect route <path> --json.

tsnavigate(to: string, options?: { replace?: boolean; scroll?: boolean }): void
prefetchRoute(pathname: string, options?: { signal?: AbortSignal }): Promise<void>
getCurrentPathname(): string
subscribePathname(listener: (pathname: string) => void): () => void
getAvailableRoutes(): PageRouteDefinition[]
subscribeAvailableRoutes(listener: (routes: PageRouteDefinition[]) => void): () => void
getResolvedRoute(pathname?: string)
getRouteStatus(pathname?: string): RouteStatus
subscribeRouteStatus(listener: (status: RouteStatus, all: RouteStatusState) => void, pathname?: string): () => void

• Link renders a real anchor and adds aria-current="page" when its resolved route is active.

• Only an unmodified primary click to the same origin is intercepted. External URLs, downloads, modified clicks, new-window targets, and same-page hashes keep browser behavior.

• replace defaults to false. Navigation scrolls to the top or hash by default; scroll: false preserves the current position. Back and forward restore saved positions.

• When an i18n service is registered, internal destinations are localized and active matching ignores the locale prefix.

tstype LinkProps = {
  to: string;
  replace?: boolean;
  scroll?: boolean;
  className?: string;
  children?: Child;
};

The standalone router is intended for embedded or client-only route areas. Do not create a second top-level router inside a file-routed application.

• RouterProvider can render explicit children or the matched route component.

• After navigation it announces status, focuses data-tavo-route-focus, main, h1, or role=main, and restores scroll.

• navigate is a no-op during server rendering. Router params are decoded strings.

tsxconst router = createRouter([
  { path: "/", component: Home },
  { path: "/teams/:id", component: Team }
]);

router.navigate("/teams/core", { replace: false, scroll: true });
router.getPathname();
router.match("/teams/core"); // { route, params: { id: "core" } }

<RouterProvider
  router={router}
  notFound={<NotFound />}
  busy={false}
  contentId="route-content"
/>