# @real-router/vue
[](../../LICENSE)
> Vue 3 integration for [Real-Router](https://github.com/greydragon888/real-router) — composables, components, and context providers.
## Installation
```bash
npm install @real-router/vue @real-router/core @real-router/browser-plugin
```
**Peer dependency:** `vue` >= 3.3.0
## Quick Start
```typescript
import { createRouter } from "@real-router/core";
import { browserPluginFactory } from "@real-router/browser-plugin";
import { RouterProvider, RouteView, Link } from "@real-router/vue";
import { defineComponent, h } from "vue";
const router = createRouter([
{ name: "home", path: "/" },
{
name: "users",
path: "/users",
children: [{ name: "profile", path: "/:id" }],
},
]);
router.usePlugin(browserPluginFactory());
router.start();
const App = defineComponent({
setup() {
return () =>
h(
RouterProvider,
{ router },
{
default: () => [
h("nav", [
h(Link, { routeName: "home" }, { default: () => "Home" }),
h(Link, { routeName: "users" }, { default: () => "Users" }),
]),
h(
RouteView,
{ nodeName: "" },
{
default: () => [
h(
RouteView.Match,
{ segment: "home" },
{ default: () => h(HomePage) },
),
h(
RouteView.Match,
{ segment: "users" },
{ default: () => h(UsersPage) },
),
h(RouteView.NotFound, null, {
default: () => h(NotFoundPage),
}),
],
},
),
],
},
);
},
});
```
Or with Vue SFC templates (the composables and components work in `.vue` files too):
```vue
```
## Plugin Installation (Alternative)
Use `createRouterPlugin` for the standard `app.use()` pattern instead of ``:
```typescript
import { createApp } from "vue";
import { createRouterPlugin } from "@real-router/vue";
const app = createApp(App);
app.use(createRouterPlugin(router));
```
All composables (`useRouter`, `useRoute`, etc.) and the `v-link` directive work identically — `app.provide()` resolves the same way as component-level `provide()`. `` remains available for advanced cases (multiple routers, scoped routing, testing).
## Composables
Route state composables return `Readonly` values — `useRoute` mirrors a `shallowRef`, `useRouteNode` derives a `computed`, and `useRouterTransition` returns a `ShallowRef` directly. Consumers only need `.value` read access; in templates Vue auto-unwraps refs.
| Composable | Returns | Reactive? |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
| `useRouter()` | `Router` | Never |
| `useNavigator()` | `Navigator` | Never (stable ref, safe to use directly) |
| `useRoute()` | `{ navigator, route: Readonly>, previousRoute: Readonly> }` | route/previousRoute on every navigation |
| `useRouteNode(name)` | `{ navigator, route: Readonly>, previousRoute: Readonly> }` (computed under the hood) | Only when node activates/deactivates |
| `useRouteUtils()` | `RouteUtils` | Never |
| `useRouterTransition()` | `ShallowRef` | On transition start/end |
| `useRouteExit(handler, options?)` | `void` — wraps `subscribeLeave` with abort + same-route guards | Never (handler captured in `setup()`) |
| `useRouteEnter(handler, options?)` | `void` — fires once on nav-driven mount via `watch(route)` + `transition.from` | Never (handler captured in `setup()`) |
```typescript
// useRouteNode — updates only when "users.*" changes
const UsersLayout = defineComponent({
setup() {
const { route } = useRouteNode("users");
return () => {
if (!route.value) return null;
switch (route.value.name) {
case "users":
return h(UsersList);
case "users.profile":
return h(UserProfile, { id: route.value.params.id });
default:
return null;
}
};
},
});
// useNavigator — stable reference, never reactive
const BackButton = defineComponent({
setup() {
const navigator = useNavigator();
return () =>
h("button", { onClick: () => navigator.navigate("home") }, "Back");
},
});
// useRouterTransition — progress bars, loading states
const GlobalProgress = defineComponent({
setup() {
const transition = useRouterTransition();
return () =>
transition.value.isTransitioning
? h("div", { class: "progress-bar" })
: null;
},
});
// useRouteExit — exit animations, draft autosave, AbortSignal-aware cleanup
const FadeOut = defineComponent({
setup() {
const box = useTemplateRef("box");
useRouteExit(async ({ signal }) => {
const el = box.value;
if (!el) return;
el.classList.add("fade-out");
const cleanup = () => el.classList.remove("fade-out");
signal.addEventListener("abort", cleanup, { once: true });
el.getBoundingClientRect(); // style flush
await Promise.allSettled(el.getAnimations().map((a) => a.finished));
cleanup();
});
return () => h("div", { ref: "box" });
},
});
// useRouteEnter — page-enter analytics, focus management, entry animations
const PageEnterAnalytics = defineComponent({
setup() {
useRouteEnter(({ route, previousRoute }) => {
analytics.track("page_enter", {
route: route.name,
from: previousRoute.name,
});
});
return () => null;
},
});
```
> **Vue handler-reactivity:** composables run once in `setup()`, so `handler`
> is captured at hook-call time. To vary behavior over time, read
> refs/computeds **inside** the handler body. See [CLAUDE.md](./CLAUDE.md) →
> "useRouteExit / useRouteEnter Handler Is Captured At Init".
## Components
### ``
Navigation link with automatic active state detection. Uses `computed()` for href and class — only the DOM attributes update when active state changes.
```typescript
h(
Link,
{
routeName: "users.profile",
routeParams: { id: "123" }, // path channel
routeSearch: { tab: "posts" }, // query channel (RFC-4 M2) — parallel to routeParams
activeClassName: "active", // default: "active"
activeStrict: false, // default: false (ancestor match)
ignoreQueryParams: true, // default: true
routeOptions: { replace: true },
},
{ default: () => "View Profile" },
);
```
In a template:
```vue
View Profile
```
`routeSearch` is the query (search) channel of the path/query split — parallel
to `routeParams`, the path channel. It 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. `` also accepts a single `to={{ name, params?, search?
}}` descriptor as an alternative to the `routeName`/`routeParams`/`routeSearch`
channel props — see [CLAUDE.md](./CLAUDE.md) → "`routeSearch` Prop" / "`to`
Descriptor Prop" for the full breakdown.
#### `hash` prop — URL fragment / tab-style UIs
```vue
Profile
Account
```
Tri-state: `undefined` preserves the current hash, `""` clears it, a value sets it. Active class is hash-aware — only the matching tab lights up. Live demo (React adapter, same API): [`examples/web/react/hash-examples/link-hash/`](../../examples/web/react/hash-examples/link-hash/) — template syntax differs, behavior is identical. See the [Hash Fragment Support](https://github.com/greydragon888/real-router/wiki/Hash) wiki page for the full surface.
### ``
Declarative route matching. Renders the first matching `` child.
```typescript
h(
RouteView,
{ nodeName: "" },
{
default: () => [
h(RouteView.Match, { segment: "users" }, { default: () => h(UsersPage) }),
h(
RouteView.Match,
{ segment: "settings" },
{ default: () => h(SettingsPage) },
),
h(RouteView.NotFound, null, { default: () => h(NotFoundPage) }),
],
},
);
```
`RouteView.Match` accepts an optional `exact` prop for strict segment matching:
```typescript
h(
RouteView.Match,
{ segment: "users", exact: true },
{ default: () => h(UsersIndex) },
);
// Only matches "users" exactly, not "users.profile"
```
**``** — renders when the active route name **exactly equals** the parent ``'s `nodeName`. Use for leaf pages where the parent route itself is the destination. Self outranks `` and yields to any activating ``. First-``-wins if multiple are provided.
```typescript
h(
RouteView,
{ nodeName: "users" },
{
default: () => [
// Active when route.name === "users" — the "directory index" of the node
h(RouteView.Self, null, { default: () => h(UsersIndex) }),
// Active when route.name === "users.profile"
h(
RouteView.Match,
{ segment: "users.profile" },
{ default: () => h(UserProfile) },
),
h(RouteView.NotFound, null, { default: () => h(NotFoundPage) }),
],
},
);
```
`RouteView.Self` also accepts an optional `fallback` prop (same semantics as `RouteView.Match.fallback`) for Suspense integration with `defineAsyncComponent`.
**`keepAlive` prop:** Vue's native `` preserves component state across navigations. Each segment gets a dedicated wrapper component so `` can track them independently.
```typescript
h(
RouteView,
{ nodeName: "", keepAlive: true },
{
default: () => [
h(RouteView.Match, { segment: "users" }, { default: () => h(UsersPage) }),
// UsersPage stays alive when navigating to settings and back
],
},
);
```
**Per-Match `keepAlive`:** `RouteView.Match` also accepts its own `keepAlive` prop for fine-grained control. This lets you keep only specific routes alive without enabling `keepAlive` on the parent ``.
```typescript
h(
RouteView,
{ nodeName: "" },
{
default: () => [
// Only UsersPage is kept alive; SettingsPage always remounts
h(
RouteView.Match,
{ segment: "users", keepAlive: true },
{ default: () => h(UsersPage) },
),
h(
RouteView.Match,
{ segment: "settings" },
{ default: () => h(SettingsPage) },
),
],
},
);
```
In a template:
```vue
```
Per-Match `keepAlive` is checked first; if any `Match` child has `keepAlive: true`, the `` wrapper is created for that segment even if the parent `` prop is not set.
**Lazy loading with `fallback`:** Pass a `fallback` prop (`VNode | (() => VNode)`) to wrap the matched content in Vue's ``. This lets you show a loading state while a `defineAsyncComponent` chunk is fetching. Works with both `keepAlive` and non-`keepAlive` modes.
```typescript
import { defineAsyncComponent, h } from "vue";
const LazyDashboard = defineAsyncComponent(() => import("./Dashboard.vue"));
h(
RouteView,
{ nodeName: "" },
{
default: () => [
h(
RouteView.Match,
{ segment: "dashboard", fallback: h(Spinner) },
{ default: () => h(LazyDashboard) },
),
],
},
);
```
In a template:
```vue
```
Without `fallback`, no `` boundary is added. The prop is optional.
### ``
Declarative error handling for navigation errors. Shows a fallback **alongside** children (not instead of) when a guard rejects or a route is not found.
```typescript
import { RouterErrorBoundary } from "@real-router/vue";
h(
RouterErrorBoundary,
{
fallback: (error, resetError) =>
h("div", { class: "toast" }, [
error.code,
h("button", { onClick: resetError }, "Dismiss"),
]),
onError: (error) => analytics.track("nav_error", { code: error.code }),
},
{
default: () =>
h(Link, { routeName: "protected" }, { default: () => "Go to Protected" }),
},
);
```
In a template:
```vue
Go to Protected
```
Auto-resets on next successful navigation. Works with both `` and imperative `router.navigate()`.
### `` / ``
Paired SSR-aware boundaries. `` renders the `fallback` slot on the server (and on the client first paint, to match SSR HTML), then swaps in the `default` slot after mount. `` is the symmetric inverse.
```vue
```
Implementation: `ref(false)` + `onMounted(() => mounted.value = true)`. Slots `default` (children) and `fallback`. End-to-end dogfooding lives in [`examples/web/vue/ssr-examples/ssr/`](../../examples/web/vue/ssr-examples/ssr/) (see `e2e/ssr-boundaries.spec.ts`).
## Directives
### `v-link`
Low-level directive for adding navigation to any element. Automatically handles click events, keyboard navigation (Enter key), and cursor styling.
In templates the directive is bound the usual way:
```vue
User Profile
```
In render functions, Vue's `h()` does NOT accept directives as raw `"v-link"` props. Use `withDirectives` to attach the directive to a VNode:
```typescript
import { defineComponent, h, withDirectives } from "vue";
import { vLink } from "@real-router/vue";
const Profile = defineComponent({
setup: () => () =>
withDirectives(h("a", null, "User Profile"), [
[vLink, { name: "users.profile", params: { id: "123" } }],
]),
});
```
Or register globally on the app and use the directive name in compiled templates:
```typescript
import { createApp } from "vue";
import { vLink } from "@real-router/vue";
const app = createApp(App);
app.directive("link", vLink);
// In templates: Home
```
In a template:
```vue
User Profile
Settings
```
**Value:**
| Property | Type | Default | Description |
| --------- | -------- | ------- | ---------------------------------- |
| `name` | `string` | — | Target route name |
| `params` | `Params` | `{}` | Route parameters |
| `options` | `object` | `{}` | Navigation options (replace, etc.) |
The directive automatically sets `cursor: pointer` and adds `role="link"` + `tabindex="0"` to non-interactive elements for accessibility.
## Vue-Specific Patterns
### Refs, Not Plain Values
Unlike the React and Preact adapters, `useRoute()` and `useRouteNode()` return `ShallowRef` values. Read `.value` in script:
```typescript
// React/Preact
const { route } = useRoute();
console.log(route?.name);
// Vue
const { route } = useRoute();
console.log(route.value?.name); // .value in script
// In template — Vue auto-unwraps
//
{{ route?.name }}
```
### Watching Route Changes
Use Vue's `watch` to react to route changes in script:
```typescript
const { route } = useRouteNode("users");
watch(route, (newRoute) => {
if (newRoute) {
document.title = `Users — ${newRoute.params.id ?? "list"}`;
}
});
```
### No .vue SFC Required
All components are plain `.ts` files using `defineComponent` + `h()`. You can use them in `.vue` SFC templates or in render functions — both work.
## Accessibility
Enable screen reader announcements for route changes:
```typescript
h(
RouterProvider,
{ router, announceNavigation: true },
{
default: () => [/* Your app */],
},
);
```
Or in a template:
```vue
```
When enabled, a visually hidden `aria-live` region announces each navigation. Focus moves to the first `