0
# @ionic/vue-router
1

2
@ionic/vue-router is a Vue Router integration library specifically designed for Ionic Vue applications. It extends standard Vue Router functionality with Ionic-specific navigation features including view stack management, tab navigation support, and mobile-optimized routing behaviors.
3

4
## Package Information
5

6
- **Package Name**: @ionic/vue-router
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @ionic/vue-router`
10

11
## Core Imports
12

13
```typescript
14
import { createRouter, createWebHistory, createWebHashHistory, createMemoryHistory } from "@ionic/vue-router";
15
```
16

17
For TypeScript types (not available as main exports, access through internal paths if needed):
18

19
```typescript
20
import type { IonicVueRouterOptions, RouteInfo, RouteAction, RouteDirection } from "@ionic/vue-router/dist/types/types";
21
```
22

23
For CommonJS:
24

25
```javascript
26
const { createRouter, createWebHistory, createWebHashHistory, createMemoryHistory } = require("@ionic/vue-router");
27
```
28

29
## Basic Usage
30

31
```typescript
32
import { createApp, inject } from 'vue';
33
import { createRouter, createWebHistory } from "@ionic/vue-router";
34
import App from './App.vue';
35

36
// Define routes
37
const routes = [
38
  { path: '/', component: () => import('./views/Home.vue') },
39
  { path: '/about', component: () => import('./views/About.vue') },
40
];
41

42
// Create router with Ionic features
43
const router = createRouter({
44
  history: createWebHistory(),
45
  routes,
46
  tabsPrefix: '/tabs/' // Optional: prefix for tab-based routes
47
});
48

49
// Create and mount app
50
const app = createApp(App);
51
app.use(router);
52
app.mount('#app');
53

54
// Access providers in components
55
export default {
56
  setup() {
57
    const navManager = inject('navManager');     // Navigation management
58
    const viewStacks = inject('viewStacks');     // View stack management
59
    return { navManager, viewStacks };
60
  }
61
};
62
```
63

64
## Architecture
65

66
@ionic/vue-router is built around several key components:
67

68
- **Enhanced Router Factory**: `createRouter` function that wraps Vue Router with Ionic-specific capabilities
69
- **History Integration**: Standard Vue Router history functions (web, hash, memory) for browser navigation
70
- **Navigation Manager**: Internal router that handles Ionic-specific navigation state and animations
71
- **View Stack System**: Manages multiple navigation stacks for complex mobile navigation patterns with multi-outlet support
72
- **Location History**: Tracks route history with mobile-specific features like back button handling
73
- **Tab Support**: Built-in support for tab-based navigation with customizable prefixes
74

75
The router enhances Vue Router by providing two key injected providers:
76
- `navManager`: Programmatic navigation with Ionic-specific features
77
- `viewStacks`: Advanced view stack management for complex navigation scenarios
78

79
## Capabilities
80

81
### Router Creation
82

83
Core router factory function and history utilities that create an enhanced Vue Router instance with Ionic navigation capabilities.
84

85
```typescript { .api }
86
function createRouter(opts: IonicVueRouterOptions): Router;
87

88
interface IonicVueRouterOptions extends RouterOptions {
89
  tabsPrefix?: string;
90
}
91
```
92

93
[Router Creation](./router-creation.md)
94

95
### Navigation Management  
96

97
Programmatic navigation APIs with Ionic-specific features like animations, directions, and tab handling.
98

99
```typescript { .api }
100
// Navigation methods available through injected navManager
101
interface NavigationManager {
102
  handleNavigate(
103
    path: RouteLocationRaw, 
104
    routerAction?: RouteAction, 
105
    routerDirection?: RouteDirection, 
106
    routerAnimation?: AnimationBuilder, 
107
    tab?: string
108
  ): void;
109
  handleNavigateBack(defaultHref?: string, routerAnimation?: AnimationBuilder): void;
110
  getCurrentRouteInfo(): RouteInfo;
111
  canGoBack(deep?: boolean): boolean;
112
  navigate(navigationOptions: ExternalNavigationOptions): void;
113
}
114
```
115

116
[Navigation Management](./navigation-management.md)
117

118
### View Stacks Management
119

120
Advanced view stack management system for handling complex navigation scenarios including multi-outlet routing, view lifecycle management, and component state preservation.
121

122
```typescript { .api }
123
// View stack methods available through injected viewStacks provider
124
interface ViewStacksManager {
125
  size(): number;
126
  getViewStack(outletId: number): ViewItem[] | undefined;
127
  createViewItem(
128
    outletId: number,
129
    vueComponent: any,
130
    matchedRoute: RouteLocationMatched,
131
    routeInfo: RouteInfo,
132
    ionPage?: HTMLElement
133
  ): ViewItem;
134
  findViewItemByRouteInfo(routeInfo: RouteInfo, outletId?: number): ViewItem | undefined;
135
  getChildrenToRender(outletId: number): ViewItem[];
136
}
137
```
138

139
[View Stacks Management](./view-stacks.md)
140

141
### Types and Interfaces
142

143
Complete TypeScript type definitions for all router functionality including route information, navigation parameters, and view management.
144

145
```typescript { .api }
146
interface RouteInfo {
147
  id?: string;
148
  routerAction?: RouteAction;
149
  routerDirection?: RouteDirection;
150
  routerAnimation?: AnimationBuilder;
151
  pathname?: string;
152
  search?: string;
153
  params?: { [k: string]: any };
154
  tab?: string;
155
}
156

157
type RouteAction = "push" | "pop" | "replace";
158
type RouteDirection = "forward" | "back" | "root" | "none";
159
```
160

161
[Types and Interfaces](./types.md)
162

163
## Dependencies
164

165
- **@ionic/vue**: Required dependency for AnimationBuilder type and Ionic integration
166
- **vue**: Vue 3 framework for component system and reactivity  
167
- **vue-router**: Vue Router 4 for core routing functionality