Create Agnostic Composable

1. Confirm the composable's purpose and API design and expected inputs/outputs.
2. Identify inputs params that should be reactive (MaybeRef / MaybeRefOrGetter).
3. Use

   toValue()

   or

   toRef()

   to normalize inputs inside reactive effects.
4. Implement the core logic of the composable using Vue's reactivity APIs.

Core Type Concepts

Type Utilities

/**
 * value or writable ref (value/ref/shallowRef/writable computed)
 */
export type MaybeRef<T = any> = T | Ref<T> | ShallowRef<T> | WritableComputedRef<T>;

/**
 * MaybeRef<T> + ComputedRef<T> + () => T
 */
export type MaybeRefOrGetter<T = any> = MaybeRef<T> | ComputedRef<T> | (() => T);

Policy and Rules

• Read-only, computed-friendly input: use

  MaybeRefOrGetter

• Needs to be writable / two-way input: use

  MaybeRef

• Parameter might be a function value (callback/predicate/comparator): do not use

  MaybeRefOrGetter

  , or you may accidentally invoke it as a getter.
• DOM/Element targets: if you want computed/derived targets, use

  MaybeRefOrGetter

  .

MaybeRefOrGetter

MaybeRef

• resolve reactive value using

  toRef()

  (e.g. watcher source)
• resolve non-reactive value using

  toValue()

Examples

useDocumentTitle

import { watch, toRef } from 'vue'
import type { MaybeRefOrGetter } from 'vue'

export function useDocumentTitle(title: MaybeRefOrGetter<string>) {
  watch(toRef(title), (t) => {
    document.title = t
  }, { immediate: true })
}

useCounter

import { watch, toRef } from 'vue'
import type { MaybeRef } from 'vue'

function useCounter(count: MaybeRef<number>) {
  const countRef = toRef(count)
  function add() {
    countRef.value++
  }
  return { add }
}