0
# Ref Utilities
1

2
Enhanced ref utilities with automatic behaviors like debouncing, throttling, automatic reset, and extended functionality.
3

4
## Capabilities
5

6
### refDebounced
7

8
Debounced version of a ref that delays updates.
9

10
```typescript { .api }
11
/**
12
 * Debounced version of ref
13
 * @param value - Source ref to debounce
14
 * @param ms - Debounce delay in milliseconds  
15
 * @param options - Debounce options
16
 * @returns Readonly ref with debounced value
17
 */
18
function refDebounced<T>(
19
  value: Ref<T>, 
20
  ms?: number, 
21
  options?: DebounceFilterOptions
22
): Readonly<Ref<T>>;
23

24
interface DebounceFilterOptions {
25
  maxWait?: MaybeRefOrGetter<number>;
26
  rejectOnCancel?: boolean;
27
}
28
```
29

30
**Usage Example:**
31

32
```typescript
33
import { refDebounced, ref } from "@vueuse/shared";
34

35
const input = ref('');
36
const debouncedInput = refDebounced(input, 500);
37

38
// input changes immediately, debouncedInput updates after 500ms delay
39
input.value = 'h';
40
input.value = 'he';
41
input.value = 'hel';
42
input.value = 'hello'; // Only this final value will appear in debouncedInput
43

44
setTimeout(() => {
45
  console.log(debouncedInput.value); // 'hello'
46
}, 600);
47
```
48

49
### refThrottled
50

51
Throttled version of a ref that limits update frequency.
52

53
```typescript { .api }
54
/**
55
 * Throttled version of ref
56
 * @param value - Source ref to throttle
57
 * @param delay - Throttle delay in milliseconds
58
 * @param trailing - Execute on trailing edge
59
 * @param leading - Execute on leading edge
60
 * @returns Readonly ref with throttled value
61
 */
62
function refThrottled<T>(
63
  value: Ref<T>, 
64
  delay?: number, 
65
  trailing?: boolean, 
66
  leading?: boolean
67
): Readonly<Ref<T>>;
68
```
69

70
**Usage Example:**
71

72
```typescript
73
import { refThrottled, ref } from "@vueuse/shared";
74

75
const scrollY = ref(0);
76
const throttledScrollY = refThrottled(scrollY, 100);
77

78
// Rapid scroll updates are throttled to every 100ms
79
window.addEventListener('scroll', () => {
80
  scrollY.value = window.scrollY;
81
});
82

83
watch(throttledScrollY, (y) => {
84
  console.log('Throttled scroll position:', y);
85
});
86
```
87

88
### refAutoReset
89

90
Ref that automatically resets to default value after a timeout.
91

92
```typescript { .api }
93
/**
94
 * Ref that automatically resets to default value after timeout
95
 * @param defaultValue - Default value to reset to
96
 * @param afterMs - Reset delay in milliseconds
97
 * @returns Ref that auto-resets
98
 */
99
function refAutoReset<T>(defaultValue: T, afterMs?: number): Ref<T>;
100
```
101

102
**Usage Example:**
103

104
```typescript
105
import { refAutoReset } from "@vueuse/shared";
106

107
// Status message that auto-clears after 3 seconds
108
const statusMessage = refAutoReset('', 3000);
109

110
const showSuccess = () => {
111
  statusMessage.value = 'Operation successful!';
112
  // Automatically becomes '' after 3 seconds
113
};
114

115
const showError = () => {
116
  statusMessage.value = 'Operation failed!';
117
  // Automatically becomes '' after 3 seconds
118
};
119
```
120

121
### refDefault
122

123
Ref with a default value when the source is nullish.
124

125
```typescript { .api }
126
/**
127
 * Ref with default value when source is nullish
128
 * @param source - Source ref
129
 * @param defaultValue - Default value for nullish cases
130
 * @returns Ref with default value handling
131
 */
132
function refDefault<T>(
133
  source: Ref<T | undefined | null>, 
134
  defaultValue: T
135
): Ref<T>;
136
```
137

138
**Usage Example:**
139

140
```typescript
141
import { refDefault, ref } from "@vueuse/shared";
142

143
const userName = ref<string | null>(null);
144
const displayName = refDefault(userName, 'Anonymous');
145

146
console.log(displayName.value); // 'Anonymous'
147

148
userName.value = 'John';
149
console.log(displayName.value); // 'John'
150

151
userName.value = null;
152
console.log(displayName.value); // 'Anonymous'
153
```
154

155
### refWithControl
156

157
Ref with explicit control over its reactivity.
158

159
```typescript { .api }
160
/**
161
 * Ref with explicit control over its reactivity
162
 * @param initial - Initial value
163
 * @param options - Control options
164
 * @returns Ref with reactivity controls
165
 */
166
function refWithControl<T>(initial: T, options?: RefWithControlOptions): RefWithControl<T>;
167

168
interface RefWithControlOptions {
169
  onBeforeChange?: (value: T, oldValue: T) => void | boolean;
170
  onChanged?: (value: T, oldValue: T) => void;
171
}
172

173
interface RefWithControl<T> extends Ref<T> {
174
  get(): T;
175
  set(value: T): void;
176
  untrackedGet(): T;
177
  silentSet(value: T): void;
178
  peek(): T;
179
  lay(value: T): void;
180
}
181
```
182

183
**Usage Example:**
184

185
```typescript
186
import { refWithControl } from "@vueuse/shared";
187

188
const controlledRef = refWithControl('initial', {
189
  onBeforeChange(value, oldValue) {
190
    console.log(`Changing from ${oldValue} to ${value}`);
191
    // Return false to prevent change
192
    return value !== 'forbidden';
193
  },
194
  onChanged(value, oldValue) {
195
    console.log(`Changed from ${oldValue} to ${value}`);
196
  }
197
});
198

199
// Normal reactive access
200
controlledRef.value = 'new value'; // Triggers watchers
201

202
// Untracked access (doesn't trigger watchers)
203
const current = controlledRef.untrackedGet();
204

205
// Silent set (doesn't trigger watchers)
206
controlledRef.silentSet('silent update');
207

208
// Peek without tracking
209
const peeked = controlledRef.peek();
210

211
// Lay value (update without triggering onBeforeChange)
212
controlledRef.lay('laid value');
213
```
214

215
### extendRef
216

217
Extend a ref with additional properties.
218

219
```typescript { .api }
220
/**
221
 * Extends ref with additional properties
222
 * @param ref - Source ref to extend
223
 * @param extend - Object with additional properties/methods
224
 * @param options - Extension options
225
 * @returns Extended ref with additional properties
226
 */
227
function extendRef<T, Extend>(
228
  ref: Ref<T>, 
229
  extend: Extend, 
230
  options?: ExtendRefOptions
231
): ShallowUnwrapRef<Extend> & Ref<T>;
232

233
interface ExtendRefOptions {
234
  enumerable?: boolean;
235
  unwrap?: boolean;
236
}
237
```
238

239
**Usage Example:**
240

241
```typescript
242
import { extendRef, ref } from "@vueuse/shared";
243

244
const count = ref(0);
245

246
const extendedCount = extendRef(count, {
247
  double: () => count.value * 2,
248
  reset: () => { count.value = 0; },
249
  increment: (by = 1) => { count.value += by; },
250
  get isEven() { return count.value % 2 === 0; }
251
});
252

253
// Use as normal ref
254
console.log(extendedCount.value); // 0
255

256
// Use extended methods
257
extendedCount.increment(5);
258
console.log(extendedCount.double()); // 10
259
console.log(extendedCount.isEven);   // false
260

261
extendedCount.reset();
262
console.log(extendedCount.value);    // 0
263
```
264

265
### createRef
266

267
Enhanced ref creation with additional options.
268

269
```typescript { .api }
270
/**
271
 * Enhanced ref creation
272
 * @param value - Initial value
273
 * @param options - Creation options
274
 * @returns Enhanced ref
275
 */
276
function createRef<T>(value: T, options?: CreateRefOptions): Ref<T>;
277

278
interface CreateRefOptions {
279
  deep?: boolean;
280
  onTrack?: (event: DebuggerEvent) => void;
281
  onTrigger?: (event: DebuggerEvent) => void;
282
}
283
```
284

285
### Core Type Utilities
286

287
Enhanced versions of Vue's core ref utilities.
288

289
```typescript { .api }
290
/**
291
 * Enhanced version of Vue's toRef with additional capabilities
292
 */
293
function toRef<T>(value: MaybeRef<T>): Ref<T>;
294
function toRef<T extends object, K extends keyof T>(
295
  object: T, 
296
  key: K, 
297
  defaultValue?: T[K]
298
): Ref<T[K]>;
299

300
/**
301
 * Enhanced version of Vue's toRefs
302
 * @param objectRef - Object ref to convert
303
 * @returns Object with refs for each property
304
 */
305
function toRefs<T extends object>(objectRef: MaybeRef<T>): ToRefs<T>;
306

307
/**
308
 * Get the value of value/ref/getter (alias for get)
309
 * @param r - Value, ref, or getter
310
 * @returns Unwrapped value
311
 */
312
function toValue<T>(r: MaybeRefOrGetter<T>): T;
313
```
314

315
**Usage Examples:**
316

317
```typescript
318
import { toRef, toRefs, toValue, ref, reactive } from "@vueuse/shared";
319

320
// toRef with default value
321
const obj = reactive({ name: 'John' });
322
const nameRef = toRef(obj, 'name', 'Anonymous');
323

324
// toRefs on ref of object
325
const userRef = ref({ name: 'John', age: 30 });
326
const { name, age } = toRefs(userRef);
327

328
// toValue with different input types
329
const staticValue = toValue('hello');           // 'hello'
330
const refValue = toValue(ref('world'));         // 'world'  
331
const getterValue = toValue(() => 'computed');  // 'computed'
332
```