Skip to content

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.

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.

PropIf omittedUse it when
matcherReads MatcherContext, whose default is an empty matcherNormally pass your table explicitly
navigationReads NavigationContext, then window.navigationSSR or an explicitly implemented adapter
notFoundUses the exported NotFound componentYou need a useful unmatched-page view
fallbackRenders no Suspense placeholderYou want visible initial/lazy loading UI
transitionCreates an internal useTransition() tupleAn ancestor needs pending state
onNavigateSuccessNo callbackObserve native navigatesuccess
onNavigateErrorNo callbackObserve 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.

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.

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.

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.