1---
2category: State
3related: useManualRefHistory
4---
5 
6# useRefHistory
7 
8Track the change history of a ref, also provides undo and redo functionality
9 
10<CourseLink href="https://vueschool.io/lessons/ref-history-with-vueuse?friend=vueuse">Learn useRefHistory with this FREE video lesson from Vue School!</CourseLink>
11 
12## Usage
13 
14```ts {5} twoslash include usage
15import { useRefHistory } from '@vueuse/core'
16import { shallowRef } from 'vue'
17 
18const counter = shallowRef(0)
19const { history, undo, redo } = useRefHistory(counter)
20```
21 
22Internally, `watch` is used to trigger a history point when the ref value is modified. This means that history points are triggered asynchronously batching modifications in the same "tick".
23 
24```ts
25// @include: usage
26// ---cut---
27counter.value += 1
28 
29await nextTick()
30console.log(history.value)
31/* [
32  { snapshot: 1, timestamp: 1601912898062 },
33  { snapshot: 0, timestamp: 1601912898061 }
34] */
35```
36 
37You can use `undo` to reset the ref value to the last history point.
38 
39```ts
40// @include: usage
41// ---cut---
42console.log(counter.value) // 1
43undo()
44console.log(counter.value) // 0
45```
46 
47### Objects / arrays
48 
49When working with objects or arrays, since changing their attributes does not change the reference, it will not trigger the committing. To track attribute changes, you would need to pass `deep: true`. It will create clones for each history record.
50 
51```ts
52import { useRefHistory } from '@vueuse/core'
53// ---cut---
54const state = ref({
55  foo: 1,
56  bar: 'bar',
57})
58 
59const { history, undo, redo } = useRefHistory(state, {
60  deep: true,
61})
62 
63state.value.foo = 2
64 
65await nextTick()
66console.log(history.value)
67/* [
68  { snapshot: { foo: 2, bar: 'bar' } },
69  { snapshot: { foo: 1, bar: 'bar' } }
70] */
71```
72 
73#### Custom Clone Function
74 
75`useRefHistory` only embeds the minimal clone function `x => JSON.parse(JSON.stringify(x))`. To use a full featured or custom clone function, you can set up via the `clone` options.
76 
77For example, using [structuredClone](https://developer.mozilla.org/en-US/docs/Web/API/structuredClone):
78 
79```ts
80import { useRefHistory } from '@vueuse/core'
81 
82const refHistory = useRefHistory(target, { clone: structuredClone })
83```
84 
85Or by using [lodash's `cloneDeep`](https://lodash.com/docs/4.17.15#cloneDeep):
86 
87```ts
88import { useRefHistory } from '@vueuse/core'
89import { cloneDeep } from 'lodash-es'
90 
91const refHistory = useRefHistory(target, { clone: cloneDeep })
92```
93 
94Or a more lightweight [`klona`](https://github.com/lukeed/klona):
95 
96```ts
97import { useRefHistory } from '@vueuse/core'
98import { klona } from 'klona'
99 
100const refHistory = useRefHistory(target, { clone: klona })
101```
102 
103#### Custom Dump and Parse Function
104 
105Instead of using the `clone` options, you can pass custom functions to control the serialization and parsing. In case you do not need history values to be objects, this can save an extra clone when undoing. It is also useful in case you want to have the snapshots already stringified to be saved to local storage for example.
106 
107```ts
108import { useRefHistory } from '@vueuse/core'
109 
110const refHistory = useRefHistory(target, {
111  dump: JSON.stringify,
112  parse: JSON.parse,
113})
114```
115 
116### History Capacity
117 
118We will keep all the history by default (unlimited) until you explicitly clear them up, you can set the maximal amount of history to be kept by `capacity` options.
119 
120```ts
121import { useRefHistory } from '@vueuse/core'
122// ---cut---
123const refHistory = useRefHistory(target, {
124  capacity: 15, // limit to 15 history records
125})
126 
127refHistory.clear() // explicitly clear all the history
128```
129 
130### History WatchOptionFlush Timing
131 
132From [Vue's documentation](https://vuejs.org/guide/essentials/watchers.html#callback-flush-timing): Vue's reactivity system buffers invalidated effects and flush them asynchronously to avoid unnecessary duplicate invocation when there are many state mutations happening in the same "tick".
133 
134In the same way as `watch`, you can modify the flush timing using the `flush` option.
135 
136```ts
137import { useRefHistory } from '@vueuse/core'
138// ---cut---
139const refHistory = useRefHistory(target, {
140  flush: 'sync', // options 'pre' (default), 'post' and 'sync'
141})
142```
143 
144The default is `'pre'`, to align this composable with the default for Vue's watchers. This also helps to avoid common issues, like several history points generated as part of a multi-step update to a ref value that can break invariants of the app state. You can use `commit()` in case you need to create multiple history points in the same "tick"
145 
146```ts
147import { useRefHistory } from '@vueuse/core'
148// ---cut---
149const r = shallowRef(0)
150const { history, commit } = useRefHistory(r)
151 
152r.value = 1
153commit()
154 
155r.value = 2
156commit()
157 
158console.log(history.value)
159/* [
160  { snapshot: 2 },
161  { snapshot: 1 },
162  { snapshot: 0 },
163] */
164```
165 
166On the other hand, when using flush `'sync'`, you can use `batch(fn)` to generate a single history point for several sync operations
167 
168```ts
169import { useRefHistory } from '@vueuse/core'
170// ---cut---
171const r = ref({ names: [], version: 1 })
172const { history, batch } = useRefHistory(r, { flush: 'sync' })
173 
174batch(() => {
175  r.value.names.push('Lena')
176  r.value.version++
177})
178 
179console.log(history.value)
180/* [
181  { snapshot: { names: [ 'Lena' ], version: 2 },
182  { snapshot: { names: [], version: 1 },
183] */
184```
185 
186If `{ flush: 'sync', deep: true }` is used, `batch` is also useful when doing a mutable `splice` in an array. `splice` can generate up to three atomic operations that will be pushed to the ref history.
187 
188```ts
189import { useRefHistory } from '@vueuse/core'
190// ---cut---
191const arr = ref([1, 2, 3])
192const { history, batch } = useRefHistory(arr, { deep: true, flush: 'sync' })
193 
194batch(() => {
195  arr.value.splice(1, 1) // batch ensures only one history point is generated
196})
197```
198 
199Another option is to avoid mutating the original ref value using `arr.value = [...arr.value].splice(1,1)`.
200 
201## Recommended Readings
202 
203- [History and Persistence](https://patak.dev/vue/history-and-persistence.html) - by [@patak-dev](https://github.com/patak-dev)
204 
205## Type Declarations
206 
207```ts
208export interface UseRefHistoryOptions<Raw, Serialized = Raw>
209  extends ConfigurableEventFilter, ConfigurableFlush {
210  /**
211   * Watch for deep changes, default to false
212   *
213   * When set to true, it will also create clones for values store in the history
214   *
215   * @default false
216   */
217  deep?: boolean
218  /**
219   * Maximum number of history to be kept. Default to unlimited.
220   */
221  capacity?: number
222  /**
223   * Clone when taking a snapshot, shortcut for dump: JSON.parse(JSON.stringify(value)).
224   * Default to false
225   *
226   * @default false
227   */
228  clone?: boolean | CloneFn<Raw>
229  /**
230   * Serialize data into the history
231   */
232  dump?: (v: Raw) => Serialized
233  /**
234   * Deserialize data from the history
235   */
236  parse?: (v: Serialized) => Raw
237  /**
238   * Function to determine if the commit should proceed
239   * @param oldValue Previous value
240   * @param newValue New value
241   * @returns boolean indicating if commit should proceed
242   */
243  shouldCommit?: (oldValue: Raw | undefined, newValue: Raw) => boolean
244}
245export interface UseRefHistoryReturn<
246  Raw,
247  Serialized,
248> extends UseManualRefHistoryReturn<Raw, Serialized> {
249  /**
250   * A ref representing if the tracking is enabled
251   */
252  isTracking: Ref<boolean>
253  /**
254   * Pause change tracking
255   */
256  pause: () => void
257  /**
258   * Resume change tracking
259   *
260   * @param [commit] if true, a history record will be create after resuming
261   */
262  resume: (commit?: boolean) => void
263  /**
264   * A sugar for auto pause and auto resuming within a function scope
265   *
266   * @param fn
267   */
268  batch: (fn: (cancel: Fn) => void) => void
269  /**
270   * Clear the data and stop the watch
271   */
272  dispose: () => void
273}
274/**
275 * Track the change history of a ref, also provides undo and redo functionality.
276 *
277 * @see https://vueuse.org/useRefHistory
278 * @param source
279 * @param options
280 */
281export declare function useRefHistory<Raw, Serialized = Raw>(
282  source: Ref<Raw>,
283  options?: UseRefHistoryOptions<Raw, Serialized>,
284): UseRefHistoryReturn<Raw, Serialized>
285```
286