Hooks

λ Router exposes a comprehensive set of hooks for accessing route state, navigation controls, and URL information. Most hooks must be used inside a component that is a descendant of the <Router> component.

Route State

useParams

Returns the dynamic route parameters extracted from the matched URL pattern.

import { useParams } from "@studiolambda/router/react";

// Route: /user/:id
// URL: /user/42
function UserProfile() {
  const { id } = useParams(); // { id: "42" }

  return <h1>User #{id}</h1>;
}

For wildcard routes, the captured path is available under the wildcard name:

// Route: /files/*path
// URL: /files/docs/readme.md
function FileViewer() {
  const { path } = useParams(); // { path: "docs/readme.md" }

  return <div>Viewing: {path}</div>;
}

usePathname

Returns the current URL pathname as a string.

import { usePathname } from "@studiolambda/router/react";

function CurrentPath() {
  const pathname = usePathname(); // "/user/42"

  return <code>{pathname}</code>;
}

useSearchParams

Returns the current search parameters and a setter. See the Navigation guide for detailed usage.

import { useSearchParams } from "@studiolambda/router/react";

function Filters() {
  const [searchParams, setSearchParams] = useSearchParams();
  const tab = searchParams.get("tab") ?? "overview";

  return (
    <div>
      <button onClick={() => setSearchParams({ tab: "overview" })}>
        Overview
      </button>
      <button onClick={() => setSearchParams({ tab: "settings" })}>
        Settings
      </button>
    </div>
  );
}

Navigation

useNavigate

Returns a navigation function. See the Navigation guide for full details.

import { useNavigate } from "@studiolambda/router/react";

function GoHome() {
  const navigate = useNavigate();

  return <button onClick={() => navigate("/")}>Home</button>;
}

useNavigation

Returns the raw Navigation object from the Navigation API.

import { useNavigation } from "@studiolambda/router/react";

function NavDebug() {
  const navigation = useNavigation();

  return <pre>Can go back: {String(navigation.canGoBack)}</pre>;
}

useBack

Returns { back, canGoBack } for backward history navigation.

import { useBack } from "@studiolambda/router/react";

function BackButton() {
  const { back, canGoBack } = useBack();

  return (
    <button disabled={!canGoBack} onClick={() => back()}>
      Back
    </button>
  );
}

useForward

Returns { forward, canGoForward } for forward history navigation.

import { useForward } from "@studiolambda/router/react";

function ForwardButton() {
  const { forward, canGoForward } = useForward();

  return (
    <button disabled={!canGoForward} onClick={() => forward()}>
      Forward
    </button>
  );
}

Navigation State

useIsPending

Returns true while a navigation transition is in progress.

import { useIsPending } from "@studiolambda/router/react";

function LoadingBar() {
  const isPending = useIsPending();

  if (!isPending) return null;
  return <div className="loading-bar" />;
}

useNavigationType

Returns the type of the most recent navigation: "push", "replace", "reload", "traverse", or null (before any navigation).

import { useNavigationType } from "@studiolambda/router/react";

function NavigationInfo() {
  const type = useNavigationType();

  return <span>Last navigation: {type ?? "none"}</span>;
}

useNavigationSignal

Returns the AbortSignal from the current navigation event, or null before any navigation. Use this to cancel stale fetch requests when a new navigation begins.

import { useNavigationSignal } from "@studiolambda/router/react";

function DataLoader() {
  const signal = useNavigationSignal();

  // Pass to fetch() to auto-cancel on navigation change.
}

Link Helpers

useActiveLinkProps

Computes active link attributes for a given href. Used internally by Link but available for custom link components.

import { useActiveLinkProps } from "@studiolambda/router/react";

function CustomLink({ href, children }) {
  const { isActive, props } = useActiveLinkProps(href, { exact: true });

  return (
    <a
      href={href}
      {...props}
      className={isActive ? "active" : undefined}
    >
      {children}
    </a>
  );
}

Options:

Option	Type	Default	Description
exact	boolean	true	true for exact pathname match, false for prefix match.

Return value:

Property	Type	Description
isActive	boolean	Whether the href matches the current pathname.
props	object	{ "data-active": true | undefined, "aria-current": "page" | undefined }

Prefetch

usePrefetch

Returns a function that triggers a route’s prefetch handler for a given URL. Used internally by Link and available for custom prefetch logic.

import { usePrefetch } from "@studiolambda/router/react";

function PreloadButton({ url }) {
  const prefetch = usePrefetch();

  return <button onMouseEnter={() => prefetch(url)}>Hover to preload</button>;
}

usePrefetchEffect

Attaches prefetch behavior to a DOM element via a ref. Used internally by Link.

import { useRef } from "react";
import { usePrefetchEffect } from "@studiolambda/router/react";

function Card({ href }) {
  const ref = useRef(null);

  usePrefetchEffect(ref, {
    href,
    on: "viewport",
    once: true,
  });

  return (
    <a ref={ref} href={href}>
      Content
    </a>
  );
}

Options:

Option	Type	Default	Description
href	string | undefined	—	The URL to prefetch.
on	"hover" | "viewport" | undefined	—	Trigger strategy. undefined disables prefetching.
once	boolean	true	Only prefetch once per element instance.
matcher	Matcher<Handler>	Context value	Override the route matcher.

Advanced

useNavigationHandlers

Creates handler functions for the Navigation API’s event.intercept(). Used internally by the Router component. Useful for building custom Router implementations.

import { useNavigationHandlers } from "@studiolambda/router/react";

const { createPrecommitHandler, createHandler } = useNavigationHandlers();

useNavigationEvents

Subscribes to Navigation API lifecycle events. Callbacks are wrapped in useEffectEvent for stable references.

import { useNavigationEvents } from "@studiolambda/router/react";

useNavigationEvents(navigation, {
  onNavigate(event) {
    console.log("Navigating to:", event.destination.url);
  },
  onNavigateSuccess() {
    console.log("Navigation complete");
  },
  onNavigateError(error) {
    console.error("Navigation failed:", error);
  },
});

useNextMatch

Returns a resolver function that matches a destination URL against the matcher. Used internally by the Router component.

import { useNextMatch } from "@studiolambda/router/react";

const resolveMatch = useNextMatch();
const match = resolveMatch("/user/42", NotFoundComponent);
// match.handler, match.params