Components

λ Router provides two primary components: Router for rendering matched routes, and Link for navigation links with prefetch support and active state detection.

Router

The Router component is the top-level entry point. It listens to the Navigation API’s navigate event, matches URLs against your routes, and renders the matched component inside a <Suspense> boundary with middleware wrapping.

import { createRouter, Router } from "@studiolambda/router/react";

function App() {
  const router = createRouter(function (route) {
    route("/").render(Home);
    route("/about").render(About);
  });

  return <Router matcher={router} />;
}

Props

Prop	Type	Default	Description
matcher	Matcher<Handler>	Context value	Route matcher created by createRouter. Falls back to MatcherContext.
notFound	ComponentType	Built-in NotFound	Component to render when no route matches the current URL.
fallback	ReactNode	undefined	Suspense fallback shown while a lazy component is loading.
navigation	Navigation	window.navigation	Override the Navigation API object. Falls back to NavigationContext then window.navigation.
transition	[boolean, StartTransitionFn]	Internal useTransition	External transition tuple for coordinating with other parts of your app.
onNavigateSuccess	() => void	undefined	Callback fired after a successful navigation.
onNavigateError	(error: unknown) => void	undefined	Callback fired when a navigation fails.

Suspense Integration

The Router wraps the matched component in a <Suspense> boundary. If the component suspends (e.g., while loading data with use()), the fallback prop determines what the user sees:

<Router matcher={router} fallback={<LoadingSpinner />} />

Because navigations are wrapped in startTransition, React keeps the previous route visible while the new one is loading. The Suspense fallback is only shown for the initial render or when there is no previous UI to hold onto.

Not Found

When no route matches the current URL, the notFound component renders:

function Custom404() {
  return (
    <div>
      <h1>Page not found</h1>
      <a href="/">Go home</a>
    </div>
  );
}

<Router matcher={router} notFound={Custom404} />;

Provided Contexts

The Router makes several context values available to all descendant components:

Context	Hook	Description
TransitionContext	useIsPending()	[isPending, startTransition] for navigation transitions.
NavigationContext	useNavigation()	The native Navigation object.
MatcherContext	—	The route matcher instance.
NavigationTypeContext	useNavigationType()	"push", "replace", "reload", "traverse", or null.
NavigationSignalContext	useNavigationSignal()	AbortSignal from the current navigation, or null.
PathnameContext	usePathname()	Current URL pathname string.
ParamsContext	useParams()	Route parameters from the matched pattern.

---

Link

The Link component renders an <a> element with router-integrated prefetch and active link detection. The Navigation API intercepts link clicks natively — no onClick or preventDefault is needed.

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

function Nav() {
  return (
    <nav>
      <Link href="/">Home</Link>
      <Link href="/about">About</Link>
      <Link href="/contact">Contact</Link>
    </nav>
  );
}

Props

Link extends all standard <a> element attributes with additional router-specific props:

Prop	Type	Default	Description
href	string	—	The destination URL.
prefetch	"hover" | "viewport"	undefined	When to trigger the route’s prefetch handler.
once	boolean	true	Only prefetch once per link instance.
matcher	Matcher<Handler>	Context value	Override the route matcher for prefetch resolution.
className	string | ((props: LinkRenderProps) => string)	—	Static class string or a function receiving { isActive }.
activeExact	boolean	true	true for exact match, false for prefix match.

Active Link Detection

Links automatically detect whether they match the current URL and apply attributes accordingly:

• data-active is set when the link is active.
• aria-current="page" is set for accessibility.

Use the className function prop for dynamic styling based on active state:

<Link
  href="/about"
  className={({ isActive }) => (isActive ? "nav-link active" : "nav-link")}
>
  About
</Link>

By default, activeExact is true, meaning /about only matches the exact pathname /about. Set activeExact={false} for prefix matching, where /about would also match /about/team:

<Link href="/docs" activeExact={false}>
  Documentation
</Link>

Prefetching

The prefetch prop controls when the link triggers the route’s prefetch handler:

• "hover" — Prefetch when the user hovers over the link (mouseenter).
• "viewport" — Prefetch when the link enters the viewport (IntersectionObserver).

<Link href="/dashboard" prefetch="hover">
  Dashboard
</Link>

<Link href="/heavy-page" prefetch="viewport">
  Heavy Page
</Link>

When prefetching from a link, the prefetch handler receives a stub NavigationPrecommitController (no-op redirect) since there is no real navigation event happening yet. The params and url in the PrefetchContext are still fully resolved from the matched route.

The once prop (default true) ensures the prefetch handler only runs once per link instance, preventing redundant data loading on repeated hovers.

See the Prefetching guide for more details on writing prefetch handlers.