feat(refManualReset): new function (#4644)

phk422 · OrbisK · ilyaliao · web-flow · commit 81bb3cde87de · 2025-09-10T04:21:06.000Z
Co-authored-by: Robin &lt;robin.kehl@singular-it.de&gt;
Co-authored-by: IlyaL &lt;ilyaliao324@gmail.com&gt;
Co-authored-by: Anthony Fu &lt;anthonyfu117@hotmail.com&gt;
diff --git a/packages/shared/index.ts b/packages/shared/index.ts
@@ -19,6 +19,7 @@ export * from './reactivePick'
 export * from './refAutoReset'
 export * from './refDebounced'
 export * from './refDefault'
+export * from './refManualReset'
 export * from './refThrottled'
 export * from './refWithControl'
 export * from './set'
diff --git a/packages/shared/refManualReset/demo.vue b/packages/shared/refManualReset/demo.vue
@@ -0,0 +1,24 @@
+<script setup lang="ts">
+import { refManualReset } from '@vueuse/core'
+
+const message = refManualReset('Default message')
+
+function setMessage() {
+  message.value = 'Changed'
+}
+function resetMessage() {
+  message.reset()
+}
+</script>
+
+<template>
+  <div>
+    <input v-model="message" type="text">
+    <button @click="setMessage()">
+      Change Message
+    </button>
+    <button @click="resetMessage()">
+      Reset Message
+    </button>
+  </div>
+</template>
diff --git a/packages/shared/refManualReset/index.md b/packages/shared/refManualReset/index.md
@@ -0,0 +1,22 @@
+---
+category: Reactivity
+alias: manualResetRef
+---
+
+# refManualReset
+
+Create a ref with manual reset functionality.
+
+## Usage
+
+```ts
+import { refManualReset } from '@vueuse/core'
+
+const message = refManualReset('default message')
+
+message.value = 'message has set'
+
+message.reset()
+
+console.log(message.value) // 'default message'
+```
diff --git a/packages/shared/refManualReset/index.test.ts b/packages/shared/refManualReset/index.test.ts
@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest'
+import { refManualReset } from './index'
+
+describe('refManualReset', () => {
+  it('should be defined', () => {
+    expect(refManualReset).toBeDefined()
+  })
+
+  it('should be default at first', () => {
+    const val = refManualReset('default')
+    expect(val.value).toBe('default')
+  })
+
+  it('should be updated', () => {
+    const val = refManualReset('default')
+
+    val.value = 'update'
+    expect(val.value).toBe('update')
+  })
+
+  it('should be reset', async () => {
+    const val = refManualReset('default')
+    val.value = 'update'
+
+    val.reset()
+    expect(val.value).toBe('default')
+  })
+})
diff --git a/packages/shared/refManualReset/index.ts b/packages/shared/refManualReset/index.ts
@@ -0,0 +1,47 @@
+import type { MaybeRefOrGetter, Ref } from 'vue'
+import type { Fn } from '../utils'
+import { customRef, toValue } from 'vue'
+
+/**
+ * Define the shape of a ref that supports manual reset functionality.
+ *
+ * This interface extends the standard `Ref` type from Vue and adds a `reset` method.
+ * The `reset` method allows the ref to be manually reset to its default value.
+ */
+export interface ManualResetRefReturn<T> extends Ref<T> {
+  reset: Fn
+}
+
+/**
+ * Create a ref with manual reset functionality.
+ *
+ * @see https://vueuse.org/refManualReset
+ * @param defaultValue The value which will be set.
+ */
+export function refManualReset<T>(defaultValue: MaybeRefOrGetter<T>) {
+  let value: T = toValue(defaultValue)
+  let trigger: Fn
+
+  const reset = () => {
+    value = toValue(defaultValue)
+    trigger()
+  }
+
+  const refValue = customRef<T>((track, _trigger) => {
+    trigger = _trigger
+    return {
+      get() {
+        track()
+        return value
+      },
+      set(newValue) {
+        value = newValue
+        trigger()
+      },
+    }
+  }) as ManualResetRefReturn<T>
+
+  refValue.reset = reset
+
+  return refValue
+}
diff --git a/test/exports/core.yaml b/test/exports/core.yaml
@@ -100,6 +100,7 @@
   refAutoReset: function
   refDebounced: function
   refDefault: function
+  refManualReset: function
   refThrottled: function
   refWithControl: function
   set: function
diff --git a/test/exports/shared.yaml b/test/exports/shared.yaml
@@ -60,6 +60,7 @@
   refAutoReset: function
   refDebounced: function
   refDefault: function
+  refManualReset: function
   refThrottled: function
   refWithControl: function
   set: function
