`customRef()`

Creates a ref with explicit control over dependency tracking and triggering.

Since Vue 3.0 Spec ↗

Syntax

customRef<T>(factory): Ref<T>

Parameters

Name	Type	Required	Description
`factory`	`(track, trigger) => { get, set }`	No	Returns get/set; call track() in get and trigger() in set.

Returns

Ref<T> — A ref with custom reactivity behavior.

Examples

<script setup lang="ts">
import { customRef } from 'vue';

function useDebouncedRef<T>(value: T, delay = 300) {
  let timer: number;
  return customRef<T>((track, trigger) => ({
    get() {
      track();
      return value;
    },
    set(v) {
      clearTimeout(timer);
      timer = setTimeout(() => {
        value = v;
        trigger();
      }, delay);
    },
  }));
}

const text = useDebouncedRef('');
</script>

Notes

customRef hands you track and trigger so you decide exactly when reads are tracked and when effects re-run. Classic use cases include debounced or throttled refs and validation-on-write. Always call track() inside get and trigger() after the value actually changes.