# @real-router/preact
[](../../LICENSE)
> Preact integration for [Real-Router](https://github.com/greydragon888/real-router) — hooks, components, and context providers.
## Installation
```bash
npm install @real-router/preact @real-router/core
```
`@real-router/core` is the entry-point dependency the API revolves around;
`@real-router/route-utils` and `@real-router/sources` are pulled in automatically
as transitive deps (used internally by `useRouteUtils` / hook subscriptions).
Add `@real-router/browser-plugin` (or `hash-plugin` / `navigation-plugin` /
`memory-plugin`) when you need History API integration — the Quick Start below
uses it.
**Peer dependency:** `preact` >= 10.28.0 (Preact 10) or ^11.0.0-0 (Preact 11 beta and later). The adapter imports DOM types (`HTMLAttributes`, `TargetedMouseEvent`) from the top-level `preact` namespace introduced in 10.28; Preact 11's JSX-namespace restructure preserves the same imports.
## Quick Start
```tsx
import { createRouter } from "@real-router/core";
import { browserPluginFactory } from "@real-router/browser-plugin";
import { RouterProvider, RouteView, Link } from "@real-router/preact";
const router = createRouter([
{ name: "home", path: "/" },
{
name: "users",
path: "/users",
children: [{ name: "profile", path: "/:id" }],
},
]);
router.usePlugin(browserPluginFactory());
router.start();
function App() {
return (
);
}
```
## Hooks
| Hook | Returns | Re-renders |
| ---------------------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `useRouter()` | `Router` | Never |
| `useNavigator()` | `Navigator` | Never (stable ref, safe to destructure) |
| `useRoute()` | `{ navigator, route, previousRoute }` | Every navigation |
| `useRouteNode(name)` | `{ navigator, route, previousRoute }` | Only when node activates/deactivates |
| `useRouteUtils()` | `RouteUtils` | Never |
| `useRouterTransition()` | `{ isTransitioning, isLeaveApproved, toRoute, fromRoute }` | On transition start/end |
| `useRouteExit(handler, options?)` | `void` — wraps `router.subscribeLeave` with abort + same-route guards | Never (stable subscription) |
| `useRouteEnter(handler, options?)` | `void` — fires on nav-driven mount via `useRoute()` snapshot | Every navigation (host component reads `useRoute()`); handler ref + subscription are stable across renders |
```tsx
// useRouteNode — re-renders only when "users.*" changes
function UsersLayout() {
const { route } = useRouteNode("users");
if (!route) return null;
switch (route.name) {
case "users":
return ;
case "users.profile":
return ;
default:
return null;
}
}
// useNavigator — stable reference, never causes re-renders
function BackButton() {
const navigator = useNavigator();
return ;
}
// useRouterTransition — progress bars, loading states
function GlobalProgress() {
const { isTransitioning } = useRouterTransition();
if (!isTransitioning) return null;
return ;
}
// useRouteExit — exit animations, draft autosave, AbortSignal-aware cleanup
function FadeOut() {
const ref = useRef(null);
useRouteExit(async ({ signal }) => {
const el = ref.current;
if (!el) return;
el.classList.add("fade-out");
const cleanup = () => el.classList.remove("fade-out");
signal.addEventListener("abort", cleanup, { once: true });
el.getBoundingClientRect(); // style flush
await Promise.allSettled(el.getAnimations().map((a) => a.finished));
cleanup();
});
return
...
;
}
// useRouteEnter — page-enter analytics, focus management, entry animations
function PageEnterAnalytics() {
useRouteEnter(({ route, previousRoute }) => {
analytics.track("page_enter", {
route: route.name,
from: previousRoute.name,
});
});
return null;
}
```
## Components
### ``
Navigation link with automatic active state detection. Re-renders only when its active status changes.
```tsx
View Profile
```
#### `hash` prop — URL fragment / tab-style UIs
```tsx
Profile
Account
```
Tri-state: `undefined` preserves the current hash, `""` clears it, a value sets it. Active class is hash-aware — only the matching tab lights up. Live demo: [`examples/web/react/hash-examples/link-hash/`](../../examples/web/react/hash-examples/link-hash/) — behavior is identical across adapters, only template syntax differs. See the [Hash Fragment Support](https://github.com/greydragon888/real-router/wiki/Hash) wiki page for the full surface.
### ``
Declarative route matching. Renders the first matching `` child; falls back to `` when the active route name equals `nodeName`, or `` for `UNKNOWN_ROUTE`.
```tsx
```
> **Note:** Unlike the React adapter, `keepAlive` is not supported. Preact has no equivalent of React's `` API. Components unmount completely when navigating away.
#### `RouteView.Match` props
| Prop | Type | Required | Description |
| ---------- | ------------------- | -------- | ----------------------------------------------------------------------------- |
| `segment` | `string` | Yes | Route segment to match |
| `exact` | `boolean` | No | When `true`, matches only the exact route (not descendants). Default: `false` |
| `fallback` | `ComponentChildren` | No | Shown while children suspend. Wraps children in `` when provided. |
| `children` | `ComponentChildren` | Yes | Content to render when the active route matches `segment` |
#### `` and ``
Three fallback slots compose inside a ``:
| Element | Fires when | Props | Render position |
| ---------------------- | --------------------------------------------------------------------------- | --------------------------------------------- | ----------------------------- |
| `` | Active route segment matches `segment` (or descendant when `exact={false}`) | `segment` / `exact` / `fallback` / `children` | Inline at source position |
| `` | Active route name **exactly equals** parent's `nodeName` | `fallback` / `children` | Appended after Match elements |
| `` | Active route name is `UNKNOWN_ROUTE` AND no Match activated | `children` | Appended after Match elements |
Precedence:
1. `` first-wins — duplicate segments short-circuit; subsequent `` with the same segment are not rendered.
2. `` first-wins — only the first `` contributes; subsequent ones are ignored.
3. `` **first-wins** — when multiple `` siblings are declared (unusual but legal), only the _first_ one renders. Symmetric with the other two slots (#1439); prefer a single `` per RouteView.
4. An activating `` suppresses both `` and ``.
5. When no `` activates: `` wins over `` if both would fire (occurs only when `nodeName === UNKNOWN_ROUTE`, narrow edge case).
```tsx
{/* route name === "users" → renders */}
{/* "users.profile" and descendants → renders */}
{/* UNKNOWN_ROUTE → renders */}
```
#### Lazy loading with `fallback` (experimental)
Preact's `lazy` and `Suspense` come from `preact/compat`. Support is experimental — test before shipping to production.
```tsx
import { lazy } from "preact/compat";
const LazyDashboard = lazy(() => import("./Dashboard"));
}>
;
```
### Advanced exports
For custom integrations (e.g., writing your own hook on top of the router
context), the low-level contexts are also exported:
```tsx
import {
RouterContext, // Raw Router instance
NavigatorContext, // Navigator (stable ref)
RouteContext, // { navigator, route, previousRoute }
type RouteViewProps,
type RouteViewMatchProps,
type RouteViewSelfProps,
type RouteViewNotFoundProps,
} from "@real-router/preact";
```
Most apps should prefer the `use*` hooks above over consuming contexts directly.
### ``
Declarative error handling for navigation errors. Shows a fallback **alongside** children (not instead of) when a guard rejects or a route is not found.
```tsx
import { RouterErrorBoundary } from "@real-router/preact";
(
{error.code}
)}
onError={(error, toRoute, fromRoute) =>
analytics.track("nav_error", {
code: error.code,
to: toRoute?.name,
from: fromRoute?.name,
})
}
>
Go to Protected
;
```
Auto-resets on next successful navigation. Works with both `` and imperative `router.navigate()`.
## SSR-feature surface — `@real-router/preact/ssr`
All SSR-aware components, hooks, and utilities live at the `/ssr` subpath — mirror of `@real-router/react/ssr` (same exports, same API). Eight exports total: ``, ``, ``, ``, ``, ``, `useDeferred`, `createHttpStatusSink`.
### `` / ``
Paired SSR-aware boundaries. `` renders `fallback` on the server (and on the client first paint, to match SSR HTML), then swaps in `children` after mount. `` is the symmetric inverse.
```tsx
import { ClientOnly, ServerOnly } from "@real-router/preact/ssr";
}>
;
```
Implementation: `useState(false)` + `useEffect(() => setMounted(true), [])` from `preact/hooks`. End-to-end dogfooding lives in [`examples/web/preact/ssr-examples/ssr/`](../../examples/web/preact/ssr-examples/ssr/) (see `e2e/ssr-boundaries.spec.ts`).
### `` / `` / `useDeferred`
Three pieces of the deferred-data pipeline (paired with [`@real-router/ssr-data-plugin`](https://www.npmjs.com/package/@real-router/ssr-data-plugin)'s `defer()` API). `` is a cross-adapter alias for Preact's `` (from `preact/compat`). ` name="key">` reads the deferred promise the loader published under that key and hands the resolved value to a render-prop via Preact's Suspense-throwing convention. `useDeferred(key)` returns the same promise for callers composing with a third-party Suspense-aware lib.
```tsx
import { Streamed, Await, useDeferred } from "@real-router/preact/ssr";
}>
name="reviews">
{(reviews) => }
;
```
End-to-end example: [`examples/web/preact/ssr-examples/ssr-streaming/`](../../examples/web/preact/ssr-examples/ssr-streaming/).
### `` / `` / `createHttpStatusSink`
Render-time HTTP status declaration for SSR responses. Mount `` inside a route component (typical use: a `` glob page) — it writes `N` to the nearest ``'s sink during render and returns `null`. After `renderToString`, read `sink.code` and pass it to your response.
```tsx
// app.tsx
import { HttpStatusCode } from "@real-router/preact/ssr";
function NotFound() {
return (
<>
Page not found
);
}
// entry-server.tsx
import { renderToString } from "preact-render-to-string";
import {
HttpStatusProvider,
createHttpStatusSink,
} from "@real-router/preact/ssr";
const sink = createHttpStatusSink();
const html = renderToString(
,
);
response.status(sink.code ?? 200).send(html);
```
| Export | Kind | Purpose |
| ------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `` | component | Writes `code` to the optional context sink during render. Last write wins across multiple instances. No-op without a provider. |
| `` | component | Supplies an `HttpStatusSink` to descendant `` via Preact context. |
| `createHttpStatusSink()` | utility | Returns a fresh `{ code: number \| undefined }` sink — construct one per request on the server, read `sink.code` after rendering. |
Loader-driven errors (`LoaderNotFound` → 404, `LoaderRedirect` → 30x) keep working as before; this component covers render-time decisions only.
## Accessibility
Enable screen reader announcements for route changes:
```tsx
{/* Your app */}
```
When enabled, a visually hidden `aria-live` region announces each navigation. Focus moves to the first `