Navigation
@tarve/router gives stack and tab navigation with typed path params, transitions and the platform back gestures.
Install
bun add @tarve/router
npm install @tarve/routerimport { 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.
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.