From 75cbfbcb7e7d009127a920b22030ebbb2a2ce4c0 Mon Sep 17 00:00:00 2001
From: Dan Pastori <dan@521dimensions.com>
Date: Thu, 7 Apr 2022 04:41:49 -0700
Subject: [PATCH] docs(migration): add programmatic navigation example to pages
 and layouts (#4072)

Co-authored-by: Pooya Parsa <pyapar@gmail.com>
---
 docs/content/migration/6.pages-and-layouts.md | 44 +++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/docs/content/migration/6.pages-and-layouts.md b/docs/content/migration/6.pages-and-layouts.md
index 472625dc54..7234cf9cca 100644
--- a/docs/content/migration/6.pages-and-layouts.md
+++ b/docs/content/migration/6.pages-and-layouts.md
@@ -177,3 +177,47 @@ definePageMeta({
 Most of the syntax and functionality are the same for the global [NuxtLink](/api/components/nuxt-link) component. If you have been using the shortcut `<NLink>` format, you should update this to use `<NuxtLink>`.
 
 `<NuxtLink>` is now a drop-in replacement for _all_ links, even external ones. You can read more about it, and how to extend it to provide your own link component, [in the docs](/api/components/nuxt-link).
+
+## Programmatic Navigation
+
+When migrating from Nuxt 2 to Nuxt 3, you will have to update how you programmatically navigate your users. In Nuxt 2, you had access to the underlying Vue Router with `this.$router`. In Nuxt 3, you can use the `navigateTo()` utility method which allows you to pass a route and parameters to Vue Router.
+
+**Note:** Ensure to always `await` on `navigateTo` or chain it's result by returning from functions.
+
+::code-group
+
+```vue [Nuxt 2]
+<script>
+export default {
+  methods: {
+    navigate(){
+      this.$router.push({
+        path: '/search',
+        query: {
+          name: 'first name',
+          type: '1'
+        }
+      })
+    }
+  }
+}
+</script>
+```
+
+```vue [Nuxt 3]
+<script setup>
+const router = useRouter();
+
+function navigate(){
+  return navigateTo({
+    path: '/search',
+    query: {
+      name: 'first name',
+      type: '1'
+    }
+  })
+}
+</script>
+```
+
+::