[Vue.js 3.0] API – Refs

# Refs

This section uses single-file component syntax for code examples

# ref

Takes an inner value and returns a reactive and mutable ref object. The ref object has a single property .value that points to the inner value.

Example:

const count = ref(0)
console.log(count.value) // 0
count.value++
console.log(count.value) // 1

If an object is assigned as a ref's value, the object is made deeply reactive by the reactive method.

Typing:

interface Ref<T> {
value: T
}
function ref<T>(value: T): Ref<T>

Sometimes we may need to specify complex types for a ref's inner value. We can do that succinctly by passing a generics argument when calling ref to override the default inference:

const foo = ref<string | number>('foo') // foo's type: Ref<string | number>
foo.value = 123 // ok!

If the type of the generic is unknown, it's recommended to cast ref to Ref<T>:

function useState<State extends string>(initial: State) {
const state = ref(initial) as Ref<State> // state.value -> State extends string
return state
}

# unref

Returns the inner value if the argument is a ref, otherwise return the argument itself. This is a sugar function for val = isRef(val) ? val.value : val.

function useFoo(x: number | Ref<number>) {
const unwrapped = unref(x) // unwrapped is guaranteed to be number now
}

# toRef

Can be used to create a ref for a property on a source reactive object. The ref can then be passed around, retaining the reactive connection to its source property.

const state = reactive({
foo: 1,
bar: 2
})
const fooRef = toRef(state, 'foo')
fooRef.value++
console.log(state.foo) // 2
state.foo++
console.log(fooRef.value) // 3

toRef is useful when you want to pass the ref of a prop to a composition function:

export default {
setup(props) {
useSomeFeature(toRef(props, 'foo'))
}
}

toRef will return a usable ref even if the source property doesn't currently exist. This makes it especially useful when working with optional props, which wouldn't be picked up by toRefs.

# toRefs

Converts a reactive object to a plain object where each property of the resulting object is a ref pointing to the corresponding property of the original object.

const state = reactive({
foo: 1,
bar: 2
})
const stateAsRefs = toRefs(state)
/*
Type of stateAsRefs:
{
foo: Ref<number>,
bar: Ref<number>
}
*/
// The ref and the original property is "linked"
state.foo++
console.log(stateAsRefs.foo.value) // 2
stateAsRefs.foo.value++
console.log(state.foo) // 3

toRefs is useful when returning a reactive object from a composition function so that the consuming component can destructure/spread the returned object without losing reactivity:

function useFeatureX() {
const state = reactive({
foo: 1,
bar: 2
})
// logic operating on state
// convert to refs when returning
return toRefs(state)
}
export default {
setup() {
// can destructure without losing reactivity
const { foo, bar } = useFeatureX()
return {
foo,
bar
}
}
}

toRefs will only generate refs for properties that are included in the source object. To create a ref for a specific property use toRef instead.

# isRef

Checks if a value is a ref object.

# customRef

Creates a customized ref with explicit control over its dependency tracking and updates triggering. It expects a factory function, which receives track and trigger functions as arguments and should return an object with get and set.

• Example using a custom ref to implement debounce with v-model:

  <input v-model="text" />
  

  function useDebouncedRef(value, delay = 200) {
  let timeout
  return customRef((track, trigger) => {
  return {
  get() {
  track()
  return value
  },
  set(newValue) {
  clearTimeout(timeout)
  timeout = setTimeout(() => {
  value = newValue
  trigger()
  }, delay)
  }
  }
  })
  }
  export default {
  setup() {
  return {
  text: useDebouncedRef('hello')
  }
  }
  }
  

Typing:

function customRef<T>(factory: CustomRefFactory<T>): Ref<T>
type CustomRefFactory<T> = (
track: () => void,
trigger: () => void
) => {
get: () => T
set: (value: T) => void
}

# shallowRef

Creates a ref that tracks its own .value mutation but doesn't make its value reactive.

const foo = shallowRef({})
// mutating the ref's value is reactive
foo.value = {}
// but the value will not be converted.
isReactive(foo.value) // false

See also: Creating Standalone Reactive Values as refs

# triggerRef

Execute any effects tied to a shallowRef manually.

const shallow = shallowRef({
greet: 'Hello, world'
})
// Logs "Hello, world" once for the first run-through
watchEffect(() => {
console.log(shallow.value.greet)
})
// This won't trigger the effect because the ref is shallow
shallow.value.greet = 'Hello, universe'
// Logs "Hello, universe"
triggerRef(shallow)

See also: Computed and Watch - watchEffect