Skip to content

Reactivity API: Utilities

isRef()

Checks if a value is a ref object.

  • Type

    function isRef<T>(r: Ref<T> | unknown): r is Ref<T>
    

    Note the return type is a type predicate, which means isRef can be used as a type guard:

    let foo: unknown
    if (isRef(foo)) {
      // foo's type is narrowed to Ref<unknown>
      foo.value
    }
    

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.

  • Type

    function unref<T>(ref: T | Ref<T>): T
    
  • Example

    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 created ref is synced with its source property: mutating the source property will update the ref, and vice-versa.

  • Type

    function toRef<T extends object, K extends keyof T>(
      object: T,
      key: K,
      defaultValue?: T[K]
    ): ToRef<T[K]>
    
    type ToRef<T> = T extends Ref ? T : Ref<T>
    
  • Example

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

    Note this is different from:

    const fooRef = ref(state.foo)
    

    The above ref is not synced with state.foo, because the ref() receives a plain string value.

    toRef() is useful when you want to pass the ref of a prop to a composable function:

    <script setup>
    const props = defineProps(/* ... */)
    
    // convert `props.foo` into a ref, then pass into
    // a composable
    useSomeFeature(toRef(props, 'foo'))
    </script>
    

    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. Each individual ref is created using toRef().

  • Type

    function toRefs<T extends object>(
      object: T
    ): {
      [K in keyof T]: ToRef<T[K]>
    }
    
    type ToRef = T extends Ref ? T : Ref<T>
    
  • Example

    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 composable 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)
    }
    
    // can destructure without losing reactivity
    const { foo, bar } = useFeatureX()
    

    toRefs will only generate refs for properties that are enumerable on the source object at call time. To create a ref for a property that may not exist yet, use toRef instead.

isProxy()

Checks if an object is a proxy created by reactive(), readonly(), shallowReactive() or shallowReadonly().

  • Type

    function isProxy(value: unknown): boolean
    

isReactive()

Checks if an object is a proxy created by reactive() or shallowReactive().

  • Type

    function isReactive(value: unknown): boolean
    

isReadonly()

Checks if an object is a proxy created by readonly() or shallowReadonly().

  • Type

    function isReadonly(value: unknown): boolean
    
Reactivity API: Utilities has loaded