Guide · v0.13.8

Navigation

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

Install

terminal
bun add @tarve/router
npm install @tarve/router
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.

MemberDoes
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, lastChangeThe 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.

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

InputHow
EscapeRouterView (backOnEscape, on by default) while the router can go back; popups keep their own Escape.
Alt+Leftrouter.attach(app) (the hotkeys option).
Mouse back buttonrouter.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.