Router Instance

The router instance returned by createRouter(), providing route navigation, guard registration, and state query capabilities.

Properties

currentRoute

• Type: Readonly<RouteLocation>
• Description: Current route location (read-only)

router.currentRoute.path
router.currentRoute.query
router.currentRoute.meta
router.currentRoute.fullPath

Methods

push()

Navigate to a new page.

push(location: RouteLocationRaw): Promise<RouteLocation>

• Regular page → uni.navigateTo
• TabBar page → uni.switchTab
• Throws NAVIGATION_DUPLICATED on duplicate navigation

await router.push('pages/about/about')
await router.push({ path: 'pages/about/about', query: { id: '1' } })
await router.push({ name: 'about' })

replace()

Replace the current page.

replace(location: RouteLocationRaw): Promise<RouteLocation>

• Regular page → uni.redirectTo
• TabBar page → uni.switchTab

await router.replace('pages/login/login')
await router.replace({ name: 'login' })

back()

Go back to the previous page or multiple pages.

back(delta?: number): Promise<void>

• delta: Number of pages to go back, defaults to 1
• Outputs warning and resolves immediately if page stack is insufficient

await router.back()
await router.back(2)

beforeEach()

Register a global before guard.

beforeEach(guard: NavigationGuard): () => void

• Returns: A function to remove this guard

const remove = router.beforeEach((to, from, next) => {
  next()
})
remove()

beforeResolve()

Register a global resolve guard.

beforeResolve(guard: NavigationGuard): () => void

afterEach()

Register a global after hook.

afterEach(guard: PostNavigationGuard): () => void

router.afterEach((to, from) => {
  if (to.meta.title) {
    uni.setNavigationBarTitle({ title: to.meta.title as string })
  }
})

getRoutes()

Get all registered route configurations.

getRoutes(): RouteConfig[]

• Returns: Shallow copy of the route config array

hasRoute()

Check if a route with the given name exists.

hasRoute(name: string): boolean

resolve()

Resolve a route location to a full RouteLocation object without executing navigation.

resolve(location: RouteLocationRaw): RouteLocation

const location = router.resolve({ name: 'about', query: { id: '1' } })
console.log(location.fullPath)

isReady()

Wait for the router to be initialized.

isReady(): Promise<void>

onError()

Register a route error handler callback.

onError(handler: RouterOnError): () => void

router.onError((error, to, from) => {
  console.error(error.code, error.message)
})

install()

Install the router to a Vue app instance (called internally by app.use(router)).

install(app: unknown): void

The installation registers the following:

• $router — Global property, accessible via this.$router
• $route — Global property (computed), accessible via this.$route for current route location
• provide — Injects the router instance via provide(ROUTER_SYMBOL, router), enabling useRouter() / useRoute()