Ripple-Reactive
API Reference

watch()

Observe changes to a specific source without tracking everything.

While effect() automatically tracks all signals read during its execution, sometimes you only want to react when a specific piece of state changes. watch() provides a precise, Vue-style watcher that runs a callback only when its explicit source changes.

Usage

watch(source, callback, options?) takes a source function, a callback, and optional configuration.

import { signal, watch } from 'ripple-reactive';

const count = signal(0);
const name = signal('Alice');

// Only runs when `count` changes
watch(
  () => count.value,
  (newCount, oldCount) => {
    console.log(`Count changed from ${oldCount} to ${newCount}`);
    // Reading name here does NOT make the watcher depend on name
    console.log(`Current name is ${name.value}`);
  }
);

count.value = 1; // Logs: Count changed from 0 to 1, Current name is Alice
name.value = 'Bob'; // Does NOT trigger the watcher

The callback inside watch() is automatically wrapped in untrack(). This means any signals you read inside the callback will not be tracked as dependencies for the watcher.

Immediate Execution

By default, watch() is lazy: the callback does not run immediately upon creation; it only runs on the next change. To make it run immediately, use { immediate: true }.

import { signal, watch } from 'ripple-reactive';

const isOnline = signal(true);

watch(
  () => isOnline.value,
  (online) => {
    console.log(`User is now ${online ? 'online' : 'offline'}`);
  },
  { immediate: true }
); 
// Logs immediately: "User is now online"

watch() vs effect()

Featureeffect()watch()
DependenciesImplicit (auto-tracked)Explicit (via source function)
ExecutionImmediateLazy by default
Callback trackingTracks all signals readCallback is untracked
Old/New valuesNoYes
Use caseUI rendering, synchronizationSide-effects on specific state changes

Real-world Example: API Calls on State Change

import { signal, watch } from 'ripple-reactive';

const searchInput = signal('');
const results = signal<string[]>([]);

watch(
  () => searchInput.value,
  async (query) => {
    if (query.length < 3) {
      results.value = [];
      return;
    }
    
    const res = await fetch(`/api/search?q=${encodeURIComponent(query)}`);
    const data = await res.json();
    results.value = data;
  }
);

Signatures

interface WatchOptions {
  immediate?: boolean;
}

function watch<T>(
  source: () => T,
  callback: (newValue: T, oldValue: T | undefined) => void,
  options?: WatchOptions
): EffectHandle;

On this page