1---
2category: Reactivity
3alias: useThrottle, throttledRef
4---
5 
6# refThrottled
7 
8Throttle changing of a ref value.
9 
10## Usage
11 
12```ts
13import { refThrottled } from '@vueuse/core'
14import { shallowRef } from 'vue'
15 
16const input = shallowRef('')
17const throttled = refThrottled(input, 1000)
18```
19 
20An example with object ref.
21 
22```js
23import { refThrottled } from '@vueuse/core'
24import { shallowRef } from 'vue'
25 
26const data = shallowRef({
27  count: 0,
28  name: 'foo',
29})
30const throttled = refThrottled(data, 1000)
31 
32data.value = { count: 1, name: 'foo' }
33console.log(throttled.value) // { count: 1, name: 'foo' } (immediate)
34 
35data.value = { count: 2, name: 'bar' }
36data.value = { count: 3, name: 'baz' }
37data.value = { count: 4, name: 'qux' }
38console.log(throttled.value) // { count: 1, name: 'foo' } (still first value)
39 
40// After 1000ms, next change will be applied
41await sleep(1100)
42data.value = { count: 5, name: 'final' }
43await nextTick()
44console.log(throttled.value) // { count: 5, name: 'final' } (updated)
45```
46 
47### Trailing
48 
49If you don't want to watch trailing changes, set 3rd param `false` (it's `true` by default):
50 
51```ts
52import { refThrottled } from '@vueuse/core'
53import { shallowRef } from 'vue'
54 
55const input = shallowRef('')
56const throttled = refThrottled(input, 1000, false)
57```
58 
59### Leading
60 
61Allows the callback to be invoked immediately (on the leading edge of the `ms` timeout). If you don't want this behavior, set the 4th param `false` (it's `true` by default):
62 
63```ts
64import { refThrottled } from '@vueuse/core'
65import { shallowRef } from 'vue'
66 
67const input = shallowRef('')
68const throttled = refThrottled(input, 1000, undefined, false)
69```
70 
71## Recommended Reading
72 
73- [Debounce vs Throttle: Definitive Visual Guide](https://kettanaito.com/blog/debounce-vs-throttle)
74- [Debouncing and Throttling Explained Through Examples](https://css-tricks.com/debouncing-throttling-explained-examples/)
75 
76## Type Declarations
77 
78```ts
79export type RefThrottledReturn<T = any> = Ref<T>
80/**
81 * Throttle execution of a function. Especially useful for rate limiting
82 * execution of handlers on events like resize and scroll.
83 *
84 * @param value Ref value to be watched with throttle effect
85 * @param  delay  A zero-or-greater delay in milliseconds. For event callbacks, values around 100 or 250 (or even higher) are most useful.
86 * @param trailing if true, update the value again after the delay time is up
87 * @param leading if true, update the value on the leading edge of the ms timeout
88 */
89export declare function refThrottled<T = any>(
90  value: Ref<T>,
91  delay?: number,
92  trailing?: boolean,
93  leading?: boolean,
94): RefThrottledReturn<T>
95/** @deprecated use `refThrottled` instead */
96export declare const throttledRef: typeof refThrottled
97/** @deprecated use `refThrottled` instead */
98export declare const useThrottle: typeof refThrottled
99```
100