Components and Loading
You need a place to render the selected page, links to reach other pages, and deliberate behavior while route code loads. Router owns matching and navigation; Link remains a real anchor; React Suspense handles suspended rendering.
The quickstart supplies the application setup and error boundary. All router imports on this page come from @studiolambda/router/react.
Render the matched page
Section titled “Render the matched page”With your existing matcher and MissingPage component, the ordinary mount is:
import { Router } from '@studiolambda/router/react'
const view = ( <Router matcher={matcher} notFound={MissingPage} fallback={<p>Opening page…</p>} onNavigateError={(error) => console.error('navigation failed', error)} />)Router takes no children and passes no props to your route component. Use hooks in pages and middleware for shared UI. The fallback is for suspended work, not errors, unmatched paths, or every interval before a navigation commits.
| Prop | If omitted | Use it when |
|---|---|---|
matcher | Reads MatcherContext, whose default is an empty matcher | Normally pass your table explicitly |
navigation | Reads NavigationContext, then window.navigation | SSR or an explicitly implemented adapter |
notFound | Uses the exported NotFound component | You need a useful unmatched-page view |
fallback | Renders no Suspense placeholder | You want visible initial/lazy loading UI |
transition | Creates an internal useTransition() tuple | An ancestor needs pending state |
onNavigateSuccess | No callback | Observe native navigatesuccess |
onNavigateError | No callback | Observe native navigateerror |
Without a supplied navigation object or browser API, Router throws rather than silently switching implementations. Native lifecycle callbacks do not report initial rendering. An ancestor error boundary is still necessary for render errors and initial guard failures.
The built-in NotFound displays Not Found in a div. Replacing it changes UI only: no HTTP status or redirect is sent. The server host owns those decisions.
Make links recognizable and accessible
Section titled “Make links recognizable and accessible”Use Link inside a page or middleware when you need active-state attributes or optional prefetch. Ordinary anchors also navigate through the native Navigation API; there is no click handler to copy:
import { Link } from '@studiolambda/router/react'
export default function LessonNavigation() { return ( <nav aria-label="Lessons"> <Link href="/lessons" activeExact={false} className={({ isActive }) => isActive ? 'selected' : 'ordinary'} > Lessons </Link> </nav> )}When active, the anchor receives data-active and aria-current="page". Style a[data-active] if you do not need a class callback. Native anchor attributes such as target, download, title, and aria-label pass through. Explicit attributes can override generated active attributes.
activeExact defaults to true. With false, /lessons is active at /lessons and /lessons/routing, but not /lessons-old. / is not a catch-all parent link. Comparison uses the pathname only and ignores query, hash, and origin; active state is not an external-URL safety check. Prefer root-relative application hrefs because helper comparisons resolve relative strings against http://localhost/, not the current page’s directory.
prefetch defaults to disabled. Choose 'hover' or 'viewport' only after reading the prefetch safety and cache rules. once defaults to true and governs the DOM trigger, not whether real navigations rerun route prefetch.
Load route code on demand
Section titled “Load route code on demand”If a page has substantial code, use React lazy so visiting another page does not require loading it first. Create src/LessonPage.tsx as shown in Defining Routes, then replace its eager import in your route-table module:
import { lazy } from 'react'import { createRouter } from '@studiolambda/router/react'
const LessonPage = lazy(() => import('./LessonPage'))const matcher = createRouter((route) => { route('/lessons/:slug').render(LessonPage)})The imported module must default-export the component. An initial visit can show Router’s fallback while the module loads. On later navigations, Router updates the route in a React transition; React can retain previously revealed content instead of replacing it with that fallback. Module rejection reaches a render error boundary, not a missing-page view.
Suspense does not fetch or cache data by itself. Use a Suspense-capable data layer for server state, with its own ownership and invalidation policy. Route prefetch may warm that layer, but it does not return loader data to the page and does not run on the initial visit.
Share transition state with an ancestor
Section titled “Share transition state with an ancestor”If a progress indicator belongs outside the routed layout, pass a useTransition tuple to Router. With your existing matcher:
import { useTransition } from 'react'import { Router } from '@studiolambda/router/react'
export default function RoutedContent() { const transition = useTransition() const [isPending] = transition return ( <> <p role="status">{isPending ? 'Opening page…' : ''}</p> <Router matcher={matcher} transition={transition} fallback={<p>Loading…</p>} /> </> )}Descendants can read the same state with useIsPending(). It measures React’s transition, not all native navigation work: precommit guards/prefetch and initial guard suspension are not covered by this boolean. Native completion also does not guarantee that every suspended subtree has painted. Use navigation events for the browser lifecycle and Suspense for initial loading.