diff --git a/packages/docs/guide/migration/index.md b/packages/docs/guide/migration/index.md
index 7e226e333..f806bf4c5 100644
--- a/packages/docs/guide/migration/index.md
+++ b/packages/docs/guide/migration/index.md
@@ -113,6 +113,19 @@ You don't need to add the `*` for repeated params if you don't plan to directly
 
 **Reason**: Vue Router doesn't use `path-to-regexp` anymore, instead it implements its own parsing system that allows route ranking and enables dynamic routing. Since we usually add one single catch-all route per project, there is no big benefit in supporting a special syntax for `*`. The encoding of params is encoding across routes, without exception to make things easier to predict.
 
+### The `currentRoute` property is now a `ref()`
+
+Previously the properties of the [`currentRoute`](https://v3.router.vuejs.org/api/#router-currentroute) object on a router instance could be accessed directly.
+
+With the introduction of vue-router v4, the underlying type of the `currentRoute` object on the router instance has changed to `Ref<RouteLocationNormalizedLoaded>`, which comes from the newer [reactivity fundamentals](https://vuejs.org/guide/essentials/reactivity-fundamentals.html) introduced in Vue 3.
+
+While this doesn't change anything if you're reading the route with `useRoute()` or `this.$route`, if you're accessing it directly on the router instance, you will need to access the actual route object via `currentRoute.value`:
+
+```ts
+const { page } = router.currentRoute.query // [!code --]
+const { page } = router.currentRoute.value.query // [!code ++]
+```
+
 ### Replaced `onReady` with `isReady`
 
 The existing `router.onReady()` function has been replaced with `router.isReady()` which doesn't take any argument and returns a Promise: