1---
2category: Sensors
3---
4 
5# useScroll
6 
7Reactive scroll position and state.
8 
9## Usage
10 
11```vue
12<script setup lang="ts">
13import { useScroll } from '@vueuse/core'
14import { useTemplateRef } from 'vue'
15 
16const el = useTemplateRef('el')
17const { x, y, isScrolling, arrivedState, directions } = useScroll(el)
18</script>
19 
20<template>
21  <div ref="el" />
22</template>
23```
24 
25### With offsets
26 
27```ts
28import { useScroll } from '@vueuse/core'
29// ---cut---
30const { x, y, isScrolling, arrivedState, directions } = useScroll(el, {
31  offset: { top: 30, bottom: 30, right: 30, left: 30 },
32})
33```
34 
35### Setting scroll position
36 
37Set the `x` and `y` values to make the element scroll to that position.
38 
39```vue
40<script setup lang="ts">
41import { useScroll } from '@vueuse/core'
42import { useTemplateRef } from 'vue'
43 
44const el = useTemplateRef('el')
45const { x, y } = useScroll(el)
46</script>
47 
48<template>
49  <div ref="el" />
50  <button @click="x += 10">
51    Scroll right 10px
52  </button>
53  <button @click="y += 10">
54    Scroll down 10px
55  </button>
56</template>
57```
58 
59### Smooth scrolling
60 
61Set `behavior: smooth` to enable smooth scrolling. The `behavior` option defaults to `auto`, which means no smooth scrolling. See the `behavior` option on [`window.scrollTo()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/scrollTo) for more information.
62 
63```ts
64import { useScroll } from '@vueuse/core'
65import { useTemplateRef } from 'vue'
66 
67const el = useTemplateRef('el')
68const { x, y } = useScroll(el, { behavior: 'smooth' })
69 
70// Or as a `ref`:
71const smooth = ref(false)
72const behavior = computed(() => smooth.value ? 'smooth' : 'auto')
73const { x, y } = useScroll(el, { behavior })
74```
75 
76### Recalculate scroll state
77 
78You can call the `measure()` method to manually update the scroll position and `arrivedState` at any time.
79 
80This is useful, for example, after dynamic content changes or when you want to recalculate the scroll state outside of scroll events.
81 
82```ts
83import { useScroll } from '@vueuse/core'
84import { nextTick, onMounted, useTemplateRef, watch } from 'vue'
85 
86const el = useTemplateRef('el')
87const reactiveValue = shallowRef(false)
88 
89const { measure } = useScroll(el)
90 
91// In a watcher
92watch(reactiveValue, () => {
93  measure()
94})
95 
96// Or inside any function
97function updateScrollState() {
98  // ...some logic
99  nextTick(() => {
100    measure()
101  })
102}
103```
104 
105> [!NOTE]
106> it's recommended to call `measure()` inside `nextTick()`, to ensure the DOM is updated first.
107> The scroll state is initialized automatically `onMount`.
108> You only need to call `measure()` manually if you want to recalculate the state after some dynamic changes.
109 
110## Directive Usage
111 
112```vue
113<script setup lang="ts">
114import type { UseScrollReturn } from '@vueuse/core'
115import { vScroll } from '@vueuse/components'
116 
117const data = ref([1, 2, 3, 4, 5, 6])
118 
119function onScroll(state: UseScrollReturn) {
120  console.log(state) // {x, y, isScrolling, arrivedState, directions}
121}
122</script>
123 
124<template>
125  <div v-scroll="onScroll">
126    <div v-for="item in data" :key="item">
127      {{ item }}
128    </div>
129  </div>
130 
131  <!-- with options -->
132  <div v-scroll="[onScroll, { throttle: 10 }]">
133    <div v-for="item in data" :key="item">
134      {{ item }}
135    </div>
136  </div>
137</template>
138```
139 
140## Type Declarations
141 
142```ts
143export interface UseScrollOptions extends ConfigurableWindow {
144  /**
145   * Throttle time for scroll event, it’s disabled by default.
146   *
147   * @default 0
148   */
149  throttle?: number
150  /**
151   * The check time when scrolling ends.
152   * This configuration will be setting to (throttle + idle) when the `throttle` is configured.
153   *
154   * @default 200
155   */
156  idle?: number
157  /**
158   * Offset arrived states by x pixels
159   *
160   */
161  offset?: {
162    left?: number
163    right?: number
164    top?: number
165    bottom?: number
166  }
167  /**
168   * Use MutationObserver to monitor specific DOM changes,
169   * such as attribute modifications, child node additions or removals, or subtree changes.
170   * @default { mutation: boolean }
171   */
172  observe?:
173    | boolean
174    | {
175        mutation?: boolean
176      }
177  /**
178   * Trigger it when scrolling.
179   *
180   */
181  onScroll?: (e: Event) => void
182  /**
183   * Trigger it when scrolling ends.
184   *
185   */
186  onStop?: (e: Event) => void
187  /**
188   * Listener options for scroll event.
189   *
190   * @default {capture: false, passive: true}
191   */
192  eventListenerOptions?: boolean | AddEventListenerOptions
193  /**
194   * Optionally specify a scroll behavior of `auto` (default, not smooth scrolling) or
195   * `smooth` (for smooth scrolling) which takes effect when changing the `x` or `y` refs.
196   *
197   * @default 'auto'
198   */
199  behavior?: MaybeRefOrGetter<ScrollBehavior>
200  /**
201   * On error callback
202   *
203   * Default log error to `console.error`
204   */
205  onError?: (error: unknown) => void
206}
207export interface UseScrollReturn {
208  x: WritableComputedRef<number>
209  y: WritableComputedRef<number>
210  isScrolling: ShallowRef<boolean>
211  arrivedState: {
212    left: boolean
213    right: boolean
214    top: boolean
215    bottom: boolean
216  }
217  directions: {
218    left: boolean
219    right: boolean
220    top: boolean
221    bottom: boolean
222  }
223  measure: () => void
224}
225/**
226 * Reactive scroll.
227 *
228 * @see https://vueuse.org/useScroll
229 * @param element
230 * @param options
231 */
232export declare function useScroll(
233  element: MaybeRefOrGetter<
234    HTMLElement | SVGElement | Window | Document | null | undefined
235  >,
236  options?: UseScrollOptions,
237): UseScrollReturn
238```
239