1---
2category: Reactivity
3alias: controlledRef
4related: computedWithControl
5---
6 
7# refWithControl
8 
9Fine-grained controls over ref and its reactivity.
10 
11## Usage
12 
13`refWithControl` uses `extendRef` to provide two extra functions `get` and `set` to have better control over when it should track/trigger the reactivity.
14 
15```ts
16import { refWithControl } from '@vueuse/core'
17 
18const num = refWithControl(0)
19const doubled = computed(() => num.value * 2)
20 
21// just like normal ref
22num.value = 42
23console.log(num.value) // 42
24console.log(doubled.value) // 84
25 
26// set value without triggering the reactivity
27num.set(30, false)
28console.log(num.value) // 30
29console.log(doubled.value) // 84 (doesn't update)
30 
31// get value without tracking the reactivity
32watchEffect(() => {
33  console.log(num.peek())
34}) // 30
35 
36num.value = 50 // watch effect wouldn't be triggered since it collected nothing.
37console.log(doubled.value) // 100 (updated again since it's a reactive set)
38```
39 
40### `peek`, `lay`, `untrackedGet`, `silentSet`
41 
42We also provide some shorthands for doing the get/set without track/triggering the reactivity system. The following lines are equivalent.
43 
44```ts
45import { refWithControl } from '@vueuse/core'
46// ---cut---
47const foo = refWithControl('foo')
48```
49 
50```ts
51import { refWithControl } from '@vueuse/core'
52 
53const foo = refWithControl('foo')
54// ---cut---
55// getting
56foo.get(false)
57foo.untrackedGet()
58foo.peek() // an alias for `untrackedGet`
59```
60 
61```ts
62import { refWithControl } from '@vueuse/core'
63 
64const foo = refWithControl('foo')
65// ---cut---
66// setting
67foo.set('bar', false)
68foo.silentSet('bar')
69foo.lay('bar') // an alias for `silentSet`
70```
71 
72## Configurations
73 
74### `onBeforeChange()`
75 
76`onBeforeChange` option is offered to give control over if a new value should be accepted. For example:
77 
78```ts
79import { refWithControl } from '@vueuse/core'
80// ---cut---
81const num = refWithControl(0, {
82  onBeforeChange(value, oldValue) {
83    // disallow changes larger then ±5 in one operation
84    if (Math.abs(value - oldValue) > 5)
85      return false // returning `false` to dismiss the change
86  },
87})
88 
89num.value += 1
90console.log(num.value) // 1
91 
92num.value += 6
93console.log(num.value) // 1 (change been dismissed)
94```
95 
96### `onChanged()`
97 
98`onChanged` option offers a similar functionally as Vue's `watch` but being synchronized with less overhead compared to `watch`.
99 
100```ts
101import { refWithControl } from '@vueuse/core'
102// ---cut---
103const num = refWithControl(0, {
104  onChanged(value, oldValue) {
105    console.log(value)
106  },
107})
108```
109 
110## Type Declarations
111 
112```ts
113export interface ControlledRefOptions<T> {
114  /**
115   * Callback function before the ref changing.
116   *
117   * Returning `false` to dismiss the change.
118   */
119  onBeforeChange?: (value: T, oldValue: T) => void | boolean
120  /**
121   * Callback function after the ref changed
122   *
123   * This happens synchronously, with less overhead compare to `watch`
124   */
125  onChanged?: (value: T, oldValue: T) => void
126}
127/**
128 * Fine-grained controls over ref and its reactivity.
129 *
130 * @__NO_SIDE_EFFECTS__
131 */
132export declare function refWithControl<T>(
133  initial: T,
134  options?: ControlledRefOptions<T>,
135): ShallowUnwrapRef<{
136  get: (tracking?: boolean) => T
137  set: (value: T, triggering?: boolean) => void
138  untrackedGet: () => T
139  silentSet: (v: T) => void
140  peek: () => T
141  lay: (v: T) => void
142}> &
143  Ref<T, T>
144/** @deprecated use `refWithControl` instead */
145export declare const controlledRef: typeof refWithControl
146```
147