# Navigation
Navigation is one factory call. `createNavigation` reads your generated `routes`
and hands back everything the client needs to move between pages: a ``, an
imperative `navigate()`, a ``, the `` that renders pages, and
the location/search hooks. The first page load is server-rendered (when SSR is
on); after that, navigation between pages is client-side (SPA-style) — no full
reload. Everything is typed against your real routes — you navigate by **point
name and params**, never by hand-built URL strings.
```tsx
// src/lib/navigation.ts
import { createNavigation } from '@point0/react-dom/router'
import {
navigate as browserNavigate,
useBrowserLocation as hook,
} from 'wouter/use-browser-location'
import { routes } from '@/generated/point0/routes'
import { AppError } from '@/lib/error' // your own error class, or just the built-in ErrorPoint0
export const {
navigate,
Link,
NavLink,
Redirect,
redirect,
Router,
RouterRoutes,
useNavLink,
InferNavigation,
} = createNavigation({
routes,
navigate: browserNavigate,
hook,
ErrorClass: AppError, // optional — defaults to ErrorPoint0
})
// Embeddable link props with this app's routes baked in (see InferNavigation, below).
export type AppLinkProps = typeof InferNavigation.LinkProps
export type AppNavLinkProps = typeof InferNavigation.NavLinkProps
```
```tsx
// anywhere in a component:
;
{idea.title}
await navigate('ideaView', { id: idea.id }) // same target, imperatively
```
You export these once and import them across the app. The rest of this page
walks each one, then the redirect mechanics, then the prefetch policy matrix.
## Setup: `createNavigation`
`routes` comes from codegen (`@/generated/point0/routes`); the `hook` is the
wouter location hook for your platform. Everything else is optional. If you omit
`routes` and never call `ClientPoints.mount(points)` first, setup throws:
```tsx
createNavigation({ navigate: browserNavigate, hook })
// throws "You should provide routes, or call ClientPoints.mount(points) before createNavigation"
```
`ErrorClass` is the error class navigation uses — it types the `error` you get
back from `navigate()` and lets `` carry your errors. It defaults to
the built-in `ErrorPoint0`; pass your own class (any class of the same or wider
shape) to override it. See [error handling](error-handling). Pass `hook` and
Point0 derives the imperative adapter-navigate and the search hook from it
automatically; passing `navigate: browserNavigate` as well (as the examples do)
is harmless but redundant when `hook` is `useBrowserLocation`.
Other options you reach for less often: `Page404` / `layout404` (rendered on no
match), `addHashToLocation`, `openExternal` (see [below](#leaving-the-spa)),
`scrollToHash`, `forceRerender`, and `prependRoutes` / `appendRoutes`. The full
list is in the [reference](#createnavigation-options).
## Links
`` renders an `` that the router intercepts — clicking it navigates
client-side (SPA-style), no full page reload. The target is one of three
mutually exclusive forms:
```tsx
Open // by point name + typed params
Open // same target, built via the routes map
Open // raw internal path
External // leaves the app (plain )
```
- `route` + `input` is the form you want almost always: `input` is typed to the
route's params, and **required exactly when the route has required params** —
omit it on `route="about"` (no params), but `route="ideaView"` forces
`input={{ id }}`.
- `to` is a raw internal path — useful when you already have a URL string, or
when you build one from the [`routes`](#the-points-route-pointroute) map
(`to={routes.ideaView({ id })}`), which some people find handier than the
point-name form.
- `href` leaves the app entirely. It renders a plain `` with no router
interception and **no prefetch** — for cross-origin or non-app URLs.
A `` accepts all native `` attributes (`className`, `target`, `rel`,
`onClick`, …):
```tsx
{idea.title}
```
It also takes `asChild` — the wouter slot pattern. With `asChild`, ``
renders no `` of its own: it clones its single child element and injects the
resolved `href` and `onClick` onto it, so your own element becomes the link. The
child must be a single valid element.
```tsx
Open{' '}
{/* MyButton receives href + onClick, no extra */}
```
`asChild` only applies to internal (`route` / `to`) links. An `href` link, or
any link opened in a new tab, always renders a plain `` and ignores
`asChild`. For turning an arbitrary component into a link by _props_ rather than
by nesting, use `splitLinkProps` instead — see
[InferNavigation](#infernavigation-embeddable-link-props).
> **GOTCHA:** an unknown `route` name on a `` does **not** throw — it logs
> an error and renders `href="#"`. `navigate(...)` with an unknown name _does_
> throw.
### Search and hash in the target
`input` carries route params plus two special keys: `'?'` for the query string
and `'#'` for the hash. They work on both `` and `navigate`:
```tsx
navigate('ideaList', { '?': { filter, sort } }) // => /ideas?filter=…&sort=…
navigate('ideaView', { id, '#': 'comments' }) // => /ideas/123#comments
```
## Imperative navigation
`navigate(route, input?, options?)` mirrors ``. It returns a promise that
resolves once the navigation settles:
```tsx
const { location, error } = await navigate('ideaView', { id: idea.id })
// location = the new location; error = an instance of your ErrorClass, or undefined
```
The most common spot is after a mutation:
```tsx
await mutation.mutateAsync(
{ title, content },
{
onSuccess: async ({ idea }) => {
await navigate('ideaView', { id: idea.id })
},
},
)
```
Variants:
```tsx
await navigate.to('/ideas/123?tab=news') // raw URL instead of a point name
navigate.back() // window.history.back() (no-op on server)
navigate.forward() // window.history.forward()
```
`navigate(...)` resolves to `{ location, error }` rather than throwing on a
failed navigation — the transition still completes and the error (logged under
the `navigation` category) is surfaced for you to inspect.
### Adapter options: replace, state
`replace` and `state` pass through to the underlying router (wouter):
```tsx
await navigate('ideaView', { id: '123' }, { replace: true }) // replace history entry, no Back trap
```
## Per-link and per-navigate options
Both `` and `navigate` take an options object for prefetch overrides,
callbacks, and tab/scroll behavior. On `navigate` it's the third argument; on
`` they're props.
```tsx
navigate('ideaView', { id }, { prefetch: 'none' }) // skip prefetch for this nav
navigate('docs', undefined, { newTab: true }) // open in a new tab
…
… // disable both triggers
```
| Option | On `navigate` | On `` | What it does |
| -------------------- | :-----------: | :---------: | ------------------------------------------------------------- |
| `prefetch` | ✓ | ✓ | Override the page's prefetch policy (both triggers on a Link) |
| `prefetchOnHover` | | ✓ | Override only the hover-prefetch policy |
| `prefetchOnNavigate` | | ✓ | Override only the click/navigate-prefetch policy |
| `before` | ✓ | ✓ | Callback run before prefetch (`(to, options) => …`) |
| `after` | ✓ | ✓ | Callback run after the navigation commits |
| `newTab` | ✓ | ✓ | Open the target in a new tab (via `openExternal`) |
| `scrollToHash` | ✓ | ✓ | Override the global scroll-to-hash policy |
On a ``, `prefetchOnHover ?? prefetch` controls hover and
`prefetchOnNavigate ?? prefetch` controls the click. Set `prefetch="none"` (or
`false`) to turn a single link's prefetch off. `before` / `after` are
fire-and-forget — they aren't awaited.
## Active links: `NavLink` and `useNavLink`
`` is `` that knows whether it points at the current location. It
sets a class based on the **match state** between the link's route and the URL:
```tsx
```
The state comes from matching the link's route against the current **pathname**
(via `route.getRelation`); `exact` vs `same` is then split by comparing the full
href. The five states:
| State | Meaning |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `exact` | the route's pathname matches **and** the full href is identical (path + search + hash) |
| `same` | the route's pathname matches but the full href differs — a different `?search`/`#hash`, or a different param value (`/ideas/1` while the link points at `/ideas/2`) |
| `ancestor` | this route is a parent of the current URL |
| `descendant` | this route is a child of the current URL |
| `unmatched` | no relation |
`className` also accepts a function or an object map, so you can express all
states in one place:
```tsx
(state.exact ? 'active' : 'idle')} />
```
For custom active UI without rendering an ``, use `useNavLink` — it returns
the state plus the resolved href:
```tsx
const { exact, ancestor, tohref } = useNavLink({ route: 'ideaList' })
return
```
## Redirects
`redirect(...)` builds a redirect — it does **nothing** by itself. You `return`
or `throw` the result, or pass it to ``. Same call shape as
`navigate`:
```tsx
redirect('signIn') // by point name
redirect('ideaView', { id }) // with params
redirect.to('/login') // raw path
redirect('signIn', undefined, { status: 308 }) // SSR HTTP status
```
There are three ways to fire one:
**From a page component** — return ``. It works under SSR (it sets the
HTTP status code) and on the client:
```tsx
export const accountPage = root.lets
.page('/account')
.page(({ props: { me } }) =>
me ? : ,
)
```
**From `.with`** (the auth-gate spot) — return a `redirect(...)`:
```tsx
export const redirectAuthorizedPlugin = Point0.lets
.plugin()
.use(mePlugin)
.with(({ props: { me } }) => (me ? redirect('home') : { me }))
.plugin()
```
**From a loader or `.ctx`** — `return` or `throw` it (both work):
```tsx
.loader(async ({ ctx }) => {
if (!ctx.me) throw redirect('signIn')
return { idea: await findIdea() }
})
```
The same `redirect(...)` value works in all three places, so an auth plugin can
gate both server loaders (in `.ctx`) and the render (in `.with`) with one helper
— see [Plugin](plugin). What happens to it depends on **where** the redirect is
produced:
- **During the initial SSR page load** — the server short-circuits the render
and replies with a real HTTP redirect carrying the status code (`302` by
default, or whatever you passed). The browser follows it before any of your JS
runs.
- **From a mutation or query** (a point fetched by the point0 client) — there is
no HTTP redirect. The redirect comes back to the client as a serialized
instruction (tagged with an `X-Point0-Redirect` header), and the client
recognizes it and performs the navigation itself — client-side, SPA-style, no
full page reload. This is why returning a `redirect(...)` from a mutation's
loader transparently moves the user without a round-trip-and-reload.
`` also takes a `task` prop directly:
```tsx
```
Valid `status` values are `301`, `302`, `303`, `307`, `308`; anything else (or
none) falls back to `302`. Note that `redirect(...)` carries `replace`/`state`
through to the adapter, so `redirect.to('/x', { replace: true })` replaces the
history entry instead of pushing.
## Reading the location
`location` is available as a prop on every page/layout component and via hooks
from `@point0/core/navigation`:
```tsx
import { useLocation, getLocation } from '@point0/core/navigation'
const location = useLocation()
location.pathname // "/ideas/123"
location.search // parsed query object
location.searchString // raw "?tab=news"
location.hash // raw "#comments" — empty unless addHash is on (see below)
location.route // the matched template, e.g. "/ideas/:id"
location.params // parsed route params
location.href // absolute; location.hrefRel = path+search+hash
```
`useLocation()` re-renders on navigation; `getLocation()` reads it imperatively
(and throws `"Current location is not yet initialized"` if called before the
router mounts).
The hash is **off by default**: `location.hash` is an empty string unless you
opt in. The underlying router doesn't track hash changes, so the hash is read
straight from `window.location.hash` only when asked. Turn it on globally with
`addHashToLocation: true` on `createNavigation`, or per read with
`useLocation({ addHash: true })` (the per-call option overrides the global
default). It's client-only — on the server the hash is always empty (the URL
fragment never reaches the server).
### Search params: `useSearch` / `setSearch`
`useSearch` returns the raw query object and a setter; pages also get
`setSearch` as a component prop:
```tsx
const [search, setSearch] = useSearch()
setSearch({ tab: 'news' }) // REPLACES the whole query → ?tab=news
setSearch({}) // clears the query
setSearch((prev) => ({ ...prev, tab })) // updater form patches; undefined drops a key
```
`setSearch` is a soft URL update — it updates the address bar without running
the navigation pipeline (no prefetch, no loading flash) and replaces the history
entry by default. It's a no-op on the server. The object form replaces the
entire query; the updater form lets you patch it. The query object here is
**raw** — it isn't coerced by a `.search` schema.
## Reacting to navigation: `useOnNavigate`
`useOnNavigate(fn)` fires when a navigation **starts**, and the cleanup it
returns runs when that navigation settles. This is the right tool for a progress
bar:
```tsx
import { useOnNavigate } from '@point0/core/navigation'
import nprogress from 'nprogress'
export const NProgress = () => {
useOnNavigate(() => {
const timeout = setTimeout(() => nprogress.start(), 30)
return () => {
clearTimeout(timeout)
nprogress.done()
}
})
return null
}
```
> **GOTCHA:** `useOnNavigate` skips the very first load and fires at navigation
> **start**, not when the new page is shown. For page-view analytics that must
> catch the first load, read `useLocation()` in an effect instead.
`useIsNavigating()` is the boolean built on top of it — dim the content while a
navigation is in flight:
```tsx
const isNavigating = useIsNavigating()
return {children}
```
## Scroll restoration
Two stage-methods on a mountable control where the page scrolls when you
navigate to it. They're set on the point chain (page/layout), not on
`createNavigation`:
```tsx
export const ideaPage = root.lets
.page('/ideas/:id')
// top of the page on every arrival (the default behavior, made explicit):
.scrollPosition('top')
// …or restore the previous scroll offset on Back/Forward:
.scrollRestore('auto')
.page(IdeaView)
```
- `.scrollPosition` decides the target scroll position when this point is shown
— e.g. jump to the top, keep the current offset, or compute one from the
location.
- `.scrollRestore` controls browser scroll restoration for this point — whether
a remembered offset is restored on history navigation (Back/Forward) or the
page starts fresh.
Cut from the server bundle — body and its imports removed (there's no scroll
position to restore on the server anyway, so it only runs in the browser) (R3:
client-only).
## The point's route: `point.route`
Every routable point carries a callable [route0](https://1gr14.dev/route0)
route. You usually navigate by name, but the route is there when you need a URL
string:
```tsx
ideaPage.route({ id: 123 }) // => "/ideas/123" (relative)
ideaPage.route.abs({ id: 123 }) // => "https://app.example.com/ideas/123"
ideaPage.route.getRelation(href) // match the current URL against this route
ideaPage.route.extend('/edit') // a new route with a suffix appended
```
- `route(input)` (≡ `route.get(input)`) builds the relative path. `input` is
required only if the route has required params.
- `route.abs(input)` builds the absolute URL using the route's configured
origin; override with `{ origin: 'https://…' }` or `{ origin: false }` for
relative.
- `route.getRelation(input)` parses a URL/location and returns the match
relation (`exact` / `ancestor` / `descendant` / `unmatched`) — this is what
`NavLink` uses under the hood.
- `route.extend(suffix)` returns a new callable route with the suffix appended.
The app-wide `routes` object (the one you feed `createNavigation`) is a map of
these callable routes, one per routable point.
## `InferNavigation`: embeddable link props
`InferNavigation` is a **type-only** export. It lets you bake your app's routes
into a component's props so any button can become a link, fully typed:
```tsx
export type AppLinkProps = typeof InferNavigation.LinkProps // route/to/href + behavior, no attrs
export type AppNavLinkProps = typeof InferNavigation.NavLinkProps
```
At runtime, split the link props off with `splitLinkProps` — this is the
production button pattern:
```tsx
import { splitLinkProps } from '@point0/react-dom/router'
type ButtonProps = MyButtonProps & AppLinkProps
function Button(props: ButtonProps) {
const [linkProps, restProps, isLink] = splitLinkProps(props)
const Comp = isLink ? Link : 'button'
return
}
// → renders a
// → renders a