49K

useRouter

Source

The useRouter composable returns the router instance.

pages/index.vue
<script setup>
const router = useRouter()
</script>

If you only need the router instance within your template, use $router:

pages/index.vue
<template>
  <button @click="$router.back()">Back</button>
</template>

If you have a pages/ directory, useRouter is identical in behavior to the one provided by vue-router.

Read vue-router documentation about the Router interface.

Basic Manipulation

  • addRoute(): Add a new route to the router instance. parentName can be provided to add new route as the child of an existing route.
  • removeRoute(): Remove an existing route by its name.
  • getRoutes(): Get a full list of all the route records.
  • hasRoute(): Checks if a route with a given name exists.
  • resolve(): Returns the normalized version of a route location. Also includes an href property that includes any existing base.
Example
const router = useRouter()

router.addRoute({ name: 'home', path: '/home', component: Home })
router.removeRoute('home')
router.getRoutes()
router.hasRoute('home')
router.resolve({ name: 'home' })
router.addRoute() adds route details into an array of routes and it is useful while building Nuxt plugins while router.push() on the other hand, triggers a new navigation immediately and it is useful in pages, Vue components and composable.

Based on History API

  • back(): Go back in history if possible, same as router.go(-1).
  • forward(): Go forward in history if possible, same as router.go(1).
  • go(): Move forward or backward through the history without the hierarchical restrictions enforced in router.back() and router.forward().
  • push(): Programmatically navigate to a new URL by pushing an entry in the history stack. It is recommended to use navigateTo instead.
  • replace(): Programmatically navigate to a new URL by replacing the current entry in the routes history stack. It is recommended to use navigateTo instead.
Example
const router = useRouter()

router.back()
router.forward()
router.go(3)
router.push({ path: "/home" })
router.replace({ hash: "#bio" })
Read more about the browser's History API.

Navigation Guards

useRouter composable provides afterEach, beforeEach and beforeResolve helper methods that acts as navigation guards.

However, Nuxt has a concept of route middleware that simplifies the implementation of navigation guards and provides a better developer experience.

Read more in Docs > Guide > Directory Structure > Middleware.

Promise and Error Handling

  • isReady(): Returns a Promise that resolves when the router has completed the initial navigation.
  • onError: Adds an error handler that is called every time a non caught error happens during navigation.
Read more in Vue Router Docs.

Universal Router Instance

If you do not have a pages/ folder, then useRouter will return a universal router instance with similar helper methods, but be aware that not all features may be supported or behave in exactly the same way as with vue-router.

useRoute

The useRoute composable returns the current route.

useRuntimeConfig

Access runtime config variables with the useRuntimeConfig composable.