customRef() Build a Ref with Custom Behaviour
Last updated: 2026-10-22
customRef() Build a Ref with Custom Behaviour
customRef() lets you control dependency tracking and triggering via a factory — the classic use is a debounced input.
| Group | Reactivity: Advanced |
|---|---|
| Kind | API |
| Scope | Component |
| Vue Version | 3.0+ |
| SSR Support | Yes |
📝 Syntax
function useDebounced(value, delay) {
return customRef((track, trigger) => ({
get() { track(); return value },
set(v) { clearTimeout(timer); timer = setTimeout(() => { value = v; trigger() }, delay) }
}))
}⚙️ Arguments
| factory | (track, trigger) => { get, set }; track collects deps, trigger notifies |
|---|
Returns：A ref with custom behaviour
▶ Example
Edit the code below and see the live result:
Output：
Typing fast updates the line only after a 400ms pause — intermediate states are merged.💡 Key Points
⚠️ Warning Always call track() and trigger(): missing track loses dependencies, missing trigger loses updates.
💡 Tip Wrap it in a composable such as useDebounced — the standard pattern.
ℹ️ Note Ideal for debounce, throttle and validated input models.
🏷️ Related Advanced
💡 Related Cases
More case studies coming soon.
📚 Related Tutorials
❓ FAQ
Q Why track manually?
A customRef hands you full control, so tracking and triggering are explicit.
Q Is customRef required for debounce?
A No — watch plus setTimeout works too; customRef is simply more cohesive.
Q Can it throttle?
A Yes — run the first write immediately and throttle subsequent ones.
