feat(useScroll): add missing measure documentation (#4727)

Matkolit · Mateusz Kołodziej · web-flow · commit dd98a7a714e4 · 2025-05-14T04:55:59.000Z
Co-authored-by: Mateusz Kołodziej &lt;mateusz@net47.pl&gt;
diff --git a/packages/core/useScroll/demo.vue b/packages/core/useScroll/demo.vue
@@ -1,11 +1,11 @@
 <script setup lang="ts">
 import { useScroll } from '@vueuse/core'
-import { computed, shallowRef, toRefs, useTemplateRef } from 'vue'
+import { computed, nextTick, shallowRef, toRefs, useTemplateRef } from 'vue'
 
 const el = useTemplateRef<HTMLElement>('el')
 const smooth = shallowRef(false)
 const behavior = computed(() => smooth.value ? 'smooth' : 'auto')
-const { x, y, isScrolling, arrivedState, directions } = useScroll(el, { behavior })
+const { x, y, isScrolling, arrivedState, directions, measure } = useScroll(el, { behavior })
 const { left, right, top, bottom } = toRefs(arrivedState)
 const { left: toLeft, right: toRight, top: toTop, bottom: toBottom } = toRefs(directions)
 
@@ -27,12 +27,20 @@ const displayY = computed({
     y.value = Number.parseFloat(val)
   },
 })
+
+const height = shallowRef<'h-[500px]' | 'h-[200px]'>('h-[500px]')
+function updateScrollPosition() {
+  height.value = height.value === 'h-[500px]' ? 'h-[200px]' : 'h-[500px]'
+  nextTick(() => {
+    measure()
+  })
+}
 </script>
 
 <template>
   <div class="flex">
     <div ref="el" class="w-300px h-300px m-auto overflow-scroll bg-gray-500/5 rounded">
-      <div class="w-500px h-400px relative">
+      <div class="w-500px relative" :class="height">
         <div position="absolute left-0 top-0" bg="gray-500/5" p="x-2 y-1">
           TopLeft
         </div>
@@ -64,7 +72,13 @@ const displayY = computed({
             <input v-model="displayY" type="number" min="0" max="100" step="10" class="w-full !min-w-0">
           </div>
         </div>
-        <label for="smooth-scrolling-option" text="right" opacity="75">Smooth scrolling</label>
+        <div class="col-span-full flex items-center justify-between">
+          Measure
+          <button @click="updateScrollPosition">
+            Toggle height
+          </button>
+        </div>
+        <label for="smooth-scrolling-option" class="whitespace-nowrap" text="right" opacity="75">Smooth scrolling</label>
         <span><input id="smooth-scrolling-option" v-model="smooth" type="checkbox"></span>
         <span text="right" opacity="75">isScrolling</span>
         <BooleanDisplay :value="isScrolling" />
diff --git a/packages/core/useScroll/index.md b/packages/core/useScroll/index.md
@@ -71,6 +71,40 @@ const behavior = computed(() => smooth.value ? 'smooth' : 'auto')
 const { x, y } = useScroll(el, { behavior })
 ```
 
+### Recalculate scroll state
+
+You can call the `measure()` method to manually update the scroll position and `arrivedState` at any time.
+
+This is useful, for example, after dynamic content changes or when you want to recalculate the scroll state outside of scroll events.
+
+```ts
+import { useScroll } from '@vueuse/core'
+import { nextTick, onMounted, useTemplateRef, watch } from 'vue'
+
+const el = useTemplateRef<HTMLElement>('el')
+const reactiveValue = shallowRef(false)
+
+const { measure } = useScroll(el)
+
+// In a watcher
+watch(reactiveValue, () => {
+  measure()
+})
+
+// Or inside any function
+function updateScrollState() {
+  // ...some logic
+  nextTick(() => {
+    measure()
+  })
+}
+```
+
+> [!NOTE]
+> it's recommended to call `measure()` inside `nextTick()`, to ensure the DOM is updated first.
+> The scroll state is initialized automatically `onMount`.
+> You only need to call `measure()` manually if you want to recalculate the state after some dynamic changes.
+
 ## Directive Usage
 
 ```vue
