1---
2category: State
3related: useRefHistory
4---
5 
6# useManualRefHistory
7 
8Manually track the change history of a ref when the using calls `commit()`, also provides undo and redo functionality
9 
10## Usage
11 
12```ts {5} twoslash include usage
13import { useManualRefHistory } from '@vueuse/core'
14import { shallowRef } from 'vue'
15 
16const counter = shallowRef(0)
17const { history, commit, undo, redo } = useManualRefHistory(counter)
18 
19counter.value += 1
20commit()
21 
22console.log(history.value)
23/* [
24  { snapshot: 1, timestamp: 1601912898062 },
25  { snapshot: 0, timestamp: 1601912898061 }
26] */
27```
28 
29You can use `undo` to reset the ref value to the last history point.
30 
31```ts
32// @include: usage
33// ---cut---
34console.log(counter.value) // 1
35undo()
36console.log(counter.value) // 0
37```
38 
39#### History of mutable objects
40 
41If you are going to mutate the source, you need to pass a custom clone function or use `clone` `true` as a param, that is a shortcut for a minimal clone function `x => JSON.parse(JSON.stringify(x))` that will be used in both `dump` and `parse`.
42 
43```ts {5}
44import { useManualRefHistory } from '@vueuse/core'
45import { ref } from 'vue'
46 
47const counter = ref({ foo: 1, bar: 2 })
48const { history, commit, undo, redo } = useManualRefHistory(counter, { clone: true })
49 
50counter.value.foo += 1
51commit()
52```
53 
54#### Custom Clone Function
55 
56To use a full featured or custom clone function, you can set up via the `clone` options.
57 
58For example, using [structuredClone](https://developer.mozilla.org/en-US/docs/Web/API/structuredClone):
59 
60```ts
61import { useManualRefHistory } from '@vueuse/core'
62 
63const refHistory = useManualRefHistory(target, { clone: structuredClone })
64```
65 
66Or by using [lodash's `cloneDeep`](https://lodash.com/docs/4.17.15#cloneDeep):
67 
68```ts
69import { useManualRefHistory } from '@vueuse/core'
70import { cloneDeep } from 'lodash-es'
71 
72const refHistory = useManualRefHistory(target, { clone: cloneDeep })
73```
74 
75Or a more lightweight [`klona`](https://github.com/lukeed/klona):
76 
77```ts
78import { useManualRefHistory } from '@vueuse/core'
79import { klona } from 'klona'
80 
81const refHistory = useManualRefHistory(target, { clone: klona })
82```
83 
84#### Custom Dump and Parse Function
85 
86Instead 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.
87 
88```ts
89import { useManualRefHistory } from '@vueuse/core'
90 
91const refHistory = useManualRefHistory(target, {
92  dump: JSON.stringify,
93  parse: JSON.parse,
94})
95```
96 
97### History Capacity
98 
99We 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.
100 
101```ts
102import { useManualRefHistory } from '@vueuse/core'
103 
104const refHistory = useManualRefHistory(target, {
105  capacity: 15, // limit to 15 history records
106})
107 
108refHistory.clear() // explicitly clear all the history
109```
110 
111## Type Declarations
112 
113```ts
114export interface UseRefHistoryRecord<T> {
115  snapshot: T
116  timestamp: number
117}
118export interface UseManualRefHistoryOptions<Raw, Serialized = Raw> {
119  /**
120   * Maximum number of history to be kept. Default to unlimited.
121   */
122  capacity?: number
123  /**
124   * Clone when taking a snapshot, shortcut for dump: JSON.parse(JSON.stringify(value)).
125   * Default to false
126   *
127   * @default false
128   */
129  clone?: boolean | CloneFn<Raw>
130  /**
131   * Serialize data into the history
132   */
133  dump?: (v: Raw) => Serialized
134  /**
135   * Deserialize data from the history
136   */
137  parse?: (v: Serialized) => Raw
138  /**
139   * set data source
140   */
141  setSource?: (source: Ref<Raw>, v: Raw) => void
142}
143export interface UseManualRefHistoryReturn<Raw, Serialized> {
144  /**
145   * Bypassed tracking ref from the argument
146   */
147  source: Ref<Raw>
148  /**
149   * An array of history records for undo, newest comes to first
150   */
151  history: Ref<UseRefHistoryRecord<Serialized>[]>
152  /**
153   * Last history point, source can be different if paused
154   */
155  last: Ref<UseRefHistoryRecord<Serialized>>
156  /**
157   * Same as {@link UseManualRefHistoryReturn.history | history}
158   */
159  undoStack: Ref<UseRefHistoryRecord<Serialized>[]>
160  /**
161   * Records array for redo
162   */
163  redoStack: Ref<UseRefHistoryRecord<Serialized>[]>
164  /**
165   * A ref representing if undo is possible (non empty undoStack)
166   */
167  canUndo: ComputedRef<boolean>
168  /**
169   * A ref representing if redo is possible (non empty redoStack)
170   */
171  canRedo: ComputedRef<boolean>
172  /**
173   * Undo changes
174   */
175  undo: () => void
176  /**
177   * Redo changes
178   */
179  redo: () => void
180  /**
181   * Clear all the history
182   */
183  clear: () => void
184  /**
185   * Create a new history record
186   */
187  commit: () => void
188  /**
189   * Reset ref's value with latest history
190   */
191  reset: () => void
192}
193/**
194 * Track the change history of a ref, also provides undo and redo functionality.
195 *
196 * @see https://vueuse.org/useManualRefHistory
197 * @param source
198 * @param options
199 */
200export declare function useManualRefHistory<Raw, Serialized = Raw>(
201  source: Ref<Raw>,
202  options?: UseManualRefHistoryOptions<Raw, Serialized>,
203): UseManualRefHistoryReturn<Raw, Serialized>
204```
205