()` accepts an optional generic so `route.params` is typed without an `as` cast at the call site (the cast happens once inside the hook — no runtime overhead). The generic types the **path** channel only — `route.search` (query channel, RFC-4 M2) keeps its own `SearchParams` shape from `@real-router/core`, always present (`{}` when there are no query params):\n\n```tsx\nimport { useRoute } from \"@real-router/solid\";\nimport type { Params } from \"@real-router/core\";\n\ntype RouteParams = { id: string } & Params;\n\nfunction UserView() {\n const routeState = useRoute();\n const id = routeState().route.params.id; // typed as string (path channel)\n const sort = routeState().route.search.sort; // query channel — not narrowed by the generic\n return
User {id}, sort {sort}
;\n}\n```\n\n`Link
` and `LinkDirectiveOptions
` accept the same generic for type-safe `routeParams`.\n\n### `useRoute()` throws when no route is active\n\n`useRoute()` returns `Accessor<{ route: State
; previousRoute?: State }>` where `route` is **non-nullable**. The hook throws if the router has no active state (unstarted, stopped, disposed) at the point of subscription. Use `useRouteNode(name)` or `useRouteStore()` if node inactivity is a legitimate state in your code path — those stay nullable. See `Gotchas` in the CLAUDE.md for the migration pattern.\n\n### Store-Based Hooks (Granular Reactivity)\n\n`useRouteStore()` and `useRouteNodeStore()` use `createStore` + `reconcile` for property-level reactivity. A component reading `state.route?.params.id` won't re-run when `state.route?.search.page` changes (granularity holds across the path/query channels, not just within one):\n\n```tsx\nimport { useRouteStore } from \"@real-router/solid\";\nimport { createEffect } from \"solid-js\";\n\nfunction UserProfile() {\n const state = useRouteStore();\n\n createEffect(() => {\n console.log(state.route?.params.id);\n });\n\n return
User: {state.route?.params.id}
;\n}\n```\n\nSignal-based hooks (`useRoute`, `useRouteNode`) remain available for simpler use cases.\n\n### Contexts (Advanced)\n\nTwo Solid contexts are exported for building custom hooks or deeply nested integrations that need direct access to router internals without prop drilling:\n\n| Context | Value type | Description |\n| --------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |\n| `RouterContext` | `RouterContextValue \\| null` — `{ router, navigator, routeSelector }` | Stable references. `routeSelector(name)` is the O(1) `createSelector`-backed active check used by ``. |\n| `RouteContext` | `Accessor \\| null` | Reactive signal. Updates on every navigation. Consumed by `useRoute()`. |\n\n```tsx\nimport { RouterContext, RouteContext } from \"@real-router/solid\";\nimport { useContext } from \"solid-js\";\n\nfunction MyCustomHook() {\n const ctx = useContext(RouterContext);\n if (!ctx) throw new Error(\"Must be used inside \");\n return ctx.router;\n}\n```\n\nFor most use cases the existing hooks (`useRouter`, `useRoute`, `useNavigator`) are sufficient — reach for raw contexts only when building custom primitives.\n\n```tsx\n// useRouteNode — updates only when \"users.*\" changes\nfunction UsersLayout() {\n const routeState = useRouteNode(\"users\");\n\n return (\n \n {(route) => {\n switch (route().name) {\n case \"users\":\n return ;\n case \"users.profile\":\n return ;\n default:\n return null;\n }\n }}\n \n );\n}\n\n// useNavigator — stable reference, never reactive\nfunction BackButton() {\n const navigator = useNavigator();\n return ;\n}\n\n// useRouterTransition — progress bars, loading states\nfunction GlobalProgress() {\n const transition = useRouterTransition();\n return (\n \n \n \n );\n}\n\n// useRouteExit — exit animations, draft autosave, AbortSignal-aware cleanup\nfunction FadeOut() {\n let ref: HTMLDivElement | undefined;\n useRouteExit(async ({ signal }) => {\n if (!ref) return;\n ref.classList.add(\"fade-out\");\n const cleanup = () => ref!.classList.remove(\"fade-out\");\n signal.addEventListener(\"abort\", cleanup, { once: true });\n ref.getBoundingClientRect(); // style flush\n await Promise.allSettled(ref.getAnimations().map((a) => a.finished));\n cleanup();\n });\n return
...
;\n}\n\n// useRouteEnter — page-enter analytics, focus management, entry animations\nfunction PageEnterAnalytics() {\n useRouteEnter(({ route, previousRoute }) => {\n analytics.track(\"page_enter\", {\n route: route.name,\n from: previousRoute.name,\n });\n });\n return null;\n}\n```\n\n> **Solid handler-reactivity:** components run once, so `handler` is captured at\n> hook-call time. To vary behavior over time, read signals **inside** the\n> handler body. See [CLAUDE.md](./CLAUDE.md) → \"useRouteExit / useRouteEnter\n> Handler Is Captured At Init\".\n\n## Components\n\n### ``\n\nNavigation link with automatic active state detection. Uses `classList` for active class toggling — only the DOM attribute updates, not the whole component.\n\n```tsx\n\n View Profile\n\n```\n\n#### `routeSearch` prop — query channel\n\n`routeSearch?: SearchParams` — the query (search) channel of the path/query split (RFC-4 M2), parallel to `routeParams`. Feeds the URL query string on click and in `href`, and — paired with `ignoreQueryParams={false}` — the active-state check.\n\n```tsx\n// Pagination link with an explicit query channel; active only on ?page=2\n\n```\n\n`routeSearch` is the only channel a route's declared `?query` may travel in — passing it inside `routeParams` is refused by core's channel guard (#1572), since the slot IS the channel.\n\n#### `to` descriptor — single-object target\n\n`` accepts two mutually-exclusive forms: the channel props above (`routeName` + `routeParams` + `routeSearch`) OR a single `to={NavigationTarget}` descriptor (`{ name, params?, search? }`). Mixing them is a compile error — TypeScript enforces the exclusion via a discriminated union (`LinkProps`), and the shared `resolveLinkTarget` helper is the runtime backstop (`to` wins, `console.warn` if channel props also leak in).\n\n```tsx\n// Channel form\n\n\n// Descriptor form — equivalent, one object\n\n```\n\n`routeOptions` and `hash` are separate props under both forms (`hash` is not part of `NavigationTarget` — #532).\n\n#### `hash` prop — URL fragment / tab-style UIs\n\n```tsx\nProfile\nAccount\n```\n\nTri-state: `undefined` preserves the current hash, `\"\"` clears it, a value sets it. Active class is hash-aware — only the matching tab lights up. Setting `hash` forces the slow path (the fast-path `routeSelector` is hash-agnostic). 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.\n\n### ``\n\nDeclarative route matching. Renders the first matching `` child.\n\n```tsx\n\n \n \n \n \n \n \n \n \n \n\n```\n\n`RouteView.Match` accepts an optional `exact` prop for strict segment matching:\n\n```tsx\n\n {/* Only matches \"users\" exactly, not \"users.profile\" */}\n \n\n```\n\n**Lazy loading with `fallback`:** Pass a `fallback` prop (`JSX.Element`) to wrap the matched content in Solid's ``. This lets you show a loading state while a `lazy()` component's chunk is fetching.\n\n```tsx\nimport { lazy } from \"solid-js\";\n\nconst LazyDashboard = lazy(() => import(\"./Dashboard\"));\n\n\n }>\n \n \n;\n```\n\nWithout `fallback`, no `` boundary is added. The prop is optional.\n\n#### `` — render the parent node itself\n\n`RouteView` shows `` children when a **descendant** route is active. To render content when the active route's name equals the parent's `nodeName` **exactly**, use ``:\n\n```tsx\n\n \n {/* active route === \"users\" exactly */}\n \n \n {/* active route is \"users.profile\" or a descendant */}\n \n \n \n \n\n```\n\n`` accepts an optional `fallback` prop (`JSX.Element`) — when provided, the children are wrapped in `` with that fallback, parallel to ``.\n\n**Precedence rules:**\n\n1. `` first-wins — if any `` activates, `` and `` are suppressed.\n2. `` first-wins — only the first `` contributes; later instances are ignored.\n3. `` wins over `` if no `` activates (rare — applies only when `nodeName === UNKNOWN_ROUTE`).\n\n| Element | Fires when | Render position |\n| ---------------------- | ------------------------------------------------------------------------- | ----------------------------- |\n| `` | Active route segment matches `segment` (or descendant if `exact={false}`) | Inline at source position |\n| `` | Active route name **exactly equals** parent's `nodeName` | Appended after Match elements |\n| `` | Active route is `UNKNOWN_ROUTE` AND no Match activated | Appended after Match elements |\n\n> **Note:** `keepAlive` is not supported. Solid has no equivalent of React's `` API. Components dispose completely when navigating away.\n\n### ``\n\nDeclarative error handling for navigation errors. Shows a fallback **alongside** children (not instead of) when a guard rejects or a route is not found.\n\n```tsx\nimport { RouterErrorBoundary } from \"@real-router/solid\";\n\n (\n
\n {error.code} \n
\n )}\n onError={(error, toRoute, fromRoute) =>\n analytics.track(\"nav_error\", {\n code: error.code,\n to: toRoute?.name,\n from: fromRoute?.name,\n })\n }\n>\n Go to Protected\n;\n```\n\nAuto-resets on next successful navigation. Works with both `` and imperative `router.navigate()`.\n\n### `` / ``\n\nPaired 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.\n\n```tsx\nimport { ClientOnly, ServerOnly } from \"@real-router/solid/ssr\";\n\n}>\n \n\n\n\n \n;\n```\n\nAll SSR-aware exports (`ClientOnly`, `ServerOnly`, `Streamed`, `Await`, `useDeferred`, `HttpStatusCode`, `HttpStatusProvider`, `createHttpStatusSink`) live at the `/ssr` subpath — the main entry stays client-only.\n\n### Render-Time HTTP Status (``)\n\nFor SSR responses that need a non-200 status (404, 410, 503, redirects), declare the code inline during render. `` writes through a `` sink and returns `null` — no DOM, no hydration mismatch. Last write wins; a no-op without a provider so the same code paths work in CSR.\n\n```tsx\nimport { renderToString } from \"solid-js/web\";\nimport {\n HttpStatusCode,\n HttpStatusProvider,\n createHttpStatusSink,\n} from \"@real-router/solid/ssr\";\n\n// In a \"page not found\" view:\nfunction NotFound() {\n return (\n <>\n \n
Page not found
\n \n );\n}\n\n// entry-server.tsx\nconst sink = createHttpStatusSink();\nconst html = renderToString(() => (\n \n \n \n));\nresponse.status(sink.code ?? 200).send(html);\n```\n\n> **Streaming SSR caveat:** with `renderToStream`, the response status MUST be sent before the first body byte flushes. If `` is mounted **inside a late-resolving ``**, the sink write happens AFTER the headers are already on the wire — the override is lost. Mount the component in the shell (above every `` that could delay it), or use `renderToStringAsync` (awaits all Suspense before returning HTML).\n\n> **Valid `code` range:** Node's `res.end()` throws `Invalid status code` on `NaN`, `0`, negative values, or `> 999` — surfaces as a 5xx / dropped connection. Pass a real HTTP status integer (100-999; commonly 4xx/5xx).\n\nImplementation: `createSignal(false)` + `onMount(() => setMounted(true))` + ``. `onMount` is SSR-safe per Solid's runtime contract — it never fires during `renderToString`/`renderToStream`. End-to-end dogfooding lives in [`examples/web/solid/ssr-examples/ssr/`](../../examples/web/solid/ssr-examples/ssr/) (see `e2e/ssr-boundaries.spec.ts`).\n\n## Directives\n\n### `use:link`\n\nLow-level directive for adding navigation to any element. Automatically handles click events, keyboard navigation (Enter key), and active state styling.\n\n```tsx\nimport { link } from \"@real-router/solid\";\n\n\n User Profile\n\n\n\n\n\n Settings\n\n```\n\n**Options:**\n\n| Option | Type | Required | Default | Description |\n| ------------------- | --------- | -------- | ------- | --------------------------------------- |\n| `routeName` | `string` | ★ yes | — | Target route name |\n| `routeParams` | `Params` | no | `{}` | Route parameters |\n| `routeOptions` | `object` | no | `{}` | Navigation options (replace, etc.) |\n| `activeClassName` | `string` | no | — | Class added when route is active |\n| `activeStrict` | `boolean` | no | `false` | Exact match only (no ancestor matching) |\n| `ignoreQueryParams` | `boolean` | no | `true` | Query params don't affect active state |\n\nThe directive automatically sets `href` on `` elements and adds `role=\"link\"` + `tabindex=\"0\"` to non-interactive elements for accessibility.\n\n> **Must be used inside ``.** The directive calls `useRouter()` internally and will throw if the host element is mounted outside the provider tree. See CLAUDE.md gotcha _\"use:link Requires useRouter Context\"_ for the failure mode and the canonical wrapping pattern.\n\n**Pass the options object directly — not an accessor (#976).** Solid's compiler wraps a directive value into an accessor at compile time (`use:link={X}` → `link(el, () => X)`), so the value you write _is_ the options object:\n\n```tsx\n// CORRECT — object form (canonical)\nHome\n\n// WRONG — accessor form double-wraps into `() => (() => options)`, so the\n// directive receives a function: the gets no href and clicks go nowhere.\n// TypeScript rejects it with TS2322.\n ({ routeName: \"home\" })}>Home\n```\n\nThe directive captures the options **once** at init (see CLAUDE.md \"use:link Options Are Captured Once\"). For reactive route switching, use the `` component instead.\n\n## Solid-Specific Patterns\n\n### Accessors, Not Values\n\nUnlike the React and Preact adapters, hooks that subscribe to route state return `Accessor`. Read the value by calling the accessor:\n\n```tsx\n// React/Preact\nconst { route } = useRoute();\n\n// Solid\nconst routeState = useRoute();\nconst { route } = routeState(); // call it\n```\n\nInside JSX, call the accessor directly in reactive positions:\n\n```tsx\nfunction CurrentRoute() {\n const routeState = useRoute();\n return
{routeState().route?.name}
;\n}\n```\n\n### Never Destructure Props\n\nSolid props are reactive getters. Destructuring them breaks the reactive graph:\n\n```tsx\n// WRONG — loses reactivity\nfunction MyLink({ routeName, routeParams }) {\n return ;\n}\n\n// CORRECT — pass props through\nfunction MyLink(props) {\n return ;\n}\n```\n\n## Accessibility\n\nEnable screen reader announcements for route changes:\n\n```tsx\n\n {/* Your app */}\n\n```\n\nWhen enabled, a visually hidden `aria-live` region announces each navigation. Focus moves to the first `
` on the new page. See [Accessibility guide](https://github.com/greydragon888/real-router/wiki/Accessibility) for details.\n\n`announceNavigation` also accepts a `RouteAnnouncerOptions` object to customize the announced text:\n\n| Option | Type | Description |\n| --------------------- | ------------------- | --------------------------------------------------------------------------------------------------- |\n| `prefix` | `string` | Prefix prepended to the resolved text (default `\"Navigated to \"`) |\n| `getAnnouncementText` | `(route) => string` | Full custom text; overrides the default `h1 → title → route-name` chain (falls back on empty/throw) |\n\n```tsx\n `Now on ${route.name}`,\n }}\n>\n {/* Your app */}\n