# Navigation

`@tarve/router` gives stack and tab navigation with typed path params, transitions and the platform back gestures.

## Install

```sh
bun add @tarve/router
npm install @tarve/router
```

```tsx title="app.tsx"
import { Button, Text, Window, createApp } from "@tarve/core";
import { Link, RouterView, createStackRouter, route } from "@tarve/router";

const router = createStackRouter({
  transition: "slide", // "none" (default) | "fade" | "slide" | { push, pop?, transition? }
  routes: {
    home: route("/", () => <Link to="/users/42">User 42</Link>),
    user: route("/users/:id", ({ params, router }) => ( // params: { id: string }
      <Button onClick={() => router.pop()}>Back from {params.id}</Button>
    )),
    notFound: route("*", () => <Text>Not found</Text>),
  },
});

const app = createApp(() => (
  <Window title="App" onCloseRequest={router.onCloseRequest}>
    <RouterView router={router} />
  </Window>
), { pointerEvents: true });
router.attach(app);
```

## Stack router

`createStackRouter({ routes, initial?, transition?, backOnCloseRequest?, onChange?, id? })`. Params are typed from the path: `:id` is required, `:tab?` optional and `*` a trailing splat.

| Member | Does |
| --- | --- |
| `push(name, params?, opts?)` / `replace(...)` | Opens a screen; `opts` takes `state` and `query`. |
| `pop(count = 1)`, `popToRoot()`, `back()`, `canGoBack()` | Walks back. |
| `reset(path?)` | Starts over at a path. |
| `navigate("/users/42?tab=posts", { replace? })` | Picks the most specific route: static, then `:param`, then `:param?`, `*` last. Returns `undefined` when nothing matches; navigating to the screen on top changes nothing. |
| `route`, `stack`, `lastChange` | The top route (a union discriminated by `name`), the whole stack and the last change. |
| `href(name, params)`, `match(path)`, `title(route?)`, `subscribe(listener)` | Helpers. |

## Tab router

`createTabRouter({ tabs, initialTab?, backBehavior?, reselectToRoot?, transition? })` keeps one stack per tab. `select(tab)` switches tabs, and selecting the active one pops it to its root. `navigate(path)` finds the tab that owns the path, the active tab first. `back()` pops the active stack, then returns to the initial tab; `backBehavior: "history"` walks the visited tabs and `"none"` stops.

```tsx title="tabs.tsx"
const tabs = createTabRouter({
  tabs: {
    feed: { title: "Feed", icon: "home", routes: { list: route("/", Feed), post: route("/posts/:id", Post) } },
    settings: { title: "Settings", routes: { main: route("/settings", Settings) } },
  },
});

<TabRouterView router={tabs} placement="bottom" />
// or <RouterView router={tabs} /> with your own <TabBar router={tabs} />
```

## Reading the route

Screens receive `route`, `params` and `router`. Components deeper in the tree call `useRoute()`, `useParams()`, `useRouter()` or `useStack()` while rendering. Tarve has no component context: `RouterView` brackets each screen with marker components, so these hooks read the screen being rendered.

Navigation inside an event handler renders like any state change. For navigation from a timer or a fetch, `router.attach(app)` makes the router call `app.update()`.

## Back

| Input | How |
| --- | --- |
| Escape | `RouterView` (`backOnEscape`, on by default) while the router can go back; popups keep their own Escape. |
| Alt+Left | `router.attach(app)` (the `hotkeys` option). |
| Mouse back button | `router.attach(app)` with `createApp(view, { pointerEvents: true })`. |
| Android back key | `<Window onCloseRequest={router.onCloseRequest}>`: the native runtime turns it into a close request. |

On Node.js, run router apps with `tarve run --runtime node`, which bundles the sources.

---

Tarve v0.13.8 · HTML version: https://tarve.dev/docs/router · Index for agents: https://tarve.dev/llms.txt
