lit · sorvell · Nov 7, 2025 · Feb 4, 2025 · Feb 27, 2025 · Feb 27, 2025
@@ -0,0 +1,5 @@
+---
+'@lit-labs/signals': minor
+---
+
+`watch` no longer triggers update; adds `effect(callback, options)`
@@ -206,31 +206,39 @@ export class SignalExample extends SignalWatcher(LitElement) {
 }
 ```
 
-`watch()` updates are batched and run in coordination with the reactive update
-lifecycle. When a watched signal changes, it is added to a batch and a reactive
-update is requested. Other changes, to reactive properties or signals accessed
-outside of `watch()`, are trigger reactive updates as usual.
-
-> [!NOTE]
->
-> <!-- -->
->
-> During a reactive update, if there are only updates from `watch()` directives,
-> then those updates are commited directly _without_ a full template render. If
-> any other changes triggered the reactive update, then the whole template is
-> re-rendered, along with the latest signal values.
-
-This approach preserves both DOM coherence and targeted updates, and coalesces
-updates when both signals and reactive properties change.
-
-`watch()` must be used in conjunction with the `SignalWatcher` mixin.
+`watch()` updates do not trigger the Lit reactive update cycle. However, they
+are batched and run in coordination with reactive updates. When a watched
+signal changes, if a reactive update is pending, the watched signal update
+renders with the update; otherwise, it renders in a batch with any other
+watched signals. Other changes, to reactive properties or signals accessed
+outside of `watch()`, trigger reactive updates as usual.
 
 You can mix and match targeted updates with `watch()` directive and
 auto-tracking with `SignalWatcher`. When you pass a signal directly to `watch()`
 it is not accessed in a callback watched by `SignalWatcher`, so an update to
 that signal will only cause a targeted DOM update and not an full template
 render.
 
+> [!NOTE]
+>
+> <!-- -->
+>
+> The value passed to `watch` must be a signal. If it isn't, it can be
+> converted to one using `computed`. For example
+> `${watch(computed(() => list.get().map(item => item))}`.
+
+### this.effect
+
+`SignalWatcher` also exposes an `effect(callback)` method that allows targeted
+reactions to signal changes independent of but coordinated with the reactive
+update lifecycle. This provides an easy mechanism to react generally to signals
+used only with `watch` that do not trigger a reactive update. By default,
+the `effect` is run after any DOM based updates are rendered, including
+the element's reactive update cycle, if it is pending when the effect would
+trigger. Adding an options argument with `beforeUpdate: true` allows effects
+to run before any DOM is updated. For example,
+`this.effect(() => console.log(this.aSignal.get())), {beforeUpdate: true});`
+
 ### html tag and withWatch()
 
 This package also exports an `html` template tag that can be used in place of