The count is ${count.get()}
\n \n `;\n }\n\n #onClick() {\n count.set(count.get() + 1);\n }\n}\n```\n\nElements should not _write_ to signals in these lifecycle methods or they might\ncause an infinite loop.\n\n### watch() directive\n\nThe `watch()` directive accepts a single Signal and renders its value,\nsubscribing to updates and updating the DOM when the signal changes. This allows\nfor very targeted updates of the DOM, which can be good for performance (but as\nalways, measure!).\n\n```ts\nimport {LitElement, html} from 'lit';\nimport {customElement, property} from 'lit/decorators.js';\nimport {SignalWatcher, watch, signal} from '@lit-labs/signals';\n\nconst count = signal(0);\n\n@customElement('signal-example')\nexport class SignalExample extends SignalWatcher(LitElement) {\n static styles = css`\n :host {\n display: block;\n }\n `;\n\n render() {\n return html`\nThe count is ${watch(count)}
\n \n `;\n }\n\n #onClick() {\n count.set(count.get() + 1);\n }\n}\n```\n\n`watch()` updates do not trigger the Lit reactive update cycle. However, they\nare batched and run in coordination with reactive updates. When a watched\nsignal changes, if a reactive update is pending, the watched signal update\nrenders with the update; otherwise, it renders in a batch with any other\nwatched signals. Other changes, to reactive properties or signals accessed\noutside of `watch()`, trigger reactive updates as usual.\n\nYou can mix and match targeted updates with `watch()` directive and\nauto-tracking with `SignalWatcher`. When you pass a signal directly to `watch()`\nit is not accessed in a callback watched by `SignalWatcher`, so an update to\nthat signal will only cause a targeted DOM update and not an full template\nrender.\n\n> [!NOTE]\n>\n> \n>\n> The value passed to `watch` must be a signal. If it isn't, it can be\n> converted to one using `computed`. For example\n> `${watch(computed(() => list.get().map(item => item))}`.\n\n### this.effect\n\n`SignalWatcher` also exposes an `effect(callback)` method that allows targeted\nreactions to signal changes independent of but coordinated with the reactive\nupdate lifecycle. This provides an easy mechanism to react generally to signals\nused only with `watch` that do not trigger a reactive update. By default,\nthe `effect` is run after any DOM based updates are rendered, including\nthe element's reactive update cycle, if it is pending when the effect would\ntrigger. Adding an options argument with `beforeUpdate: true` allows effects\nto run before any DOM is updated. For example,\n`this.effect(() => console.log(this.aSignal.get())), {beforeUpdate: true});`\n\n### html tag and withWatch()\n\nThis package also exports an `html` template tag that can be used in place of\nLit's default `html` tag and automatically wraps any signals in `watch()`.\n\n```ts\nimport {LitElement} from 'lit';\nimport {customElement, property} from 'lit/decorators.js';\nimport {SignalWatcher, html, signal} from '@lit-labs/signals';\n\nconst count = signal(0);\n\n@customElement('signal-example')\nexport class SignalExample extends SignalWatcher(LitElement) {\n static styles = css`\n :host {\n display: block;\n }\n `;\n\n render() {\n return html`\nThe count is ${count}
\n \n `;\n }\n\n #onClick() {\n count.set(count.get() + 1);\n }\n}\n```\n\n#### `withWatch()`\n\n`withWatch()` is a function that wraps an `html` tag function with the\nauto-watching functionality. The `html` tag exported by `@lit-labs/signals` is a\nconvenient export of the core lit-html template tag wrapped with `withWatch()`.\n\n`withWatch()` allows you to compose the signal watching wrapper with other\nlit-html tag wrappers like Lit's `withStatic()` utility.\n\n```ts\nimport {html as coreHtml} from 'lit';\nimport {withStatic} from 'lit/static-html.js';\nimport {withWatch} from '@lit-labs/signals';\n\n/**\n * A Lit template tag that support static values and pinpoint signal updates.\n */\nconst html = withWatch(withStatic(coreHtml));\n```\n\n## Future Work\n\nThis library will change based on feedback from developers. Some existing dieas we have for futher development are:\n\n- A signal-aware `repeat()` directive that can update items in a list independently of the entire list.\n- Signal aware `when()` directive that wraps the condition in a computed signal and watches it.\n- A `@property()` decorator that creates a signal-backed property that can be watched.\n- An `@effect()` method decorator that runs a method inside a watched computed signal, and re-runs it when any signal dependencies change. This would be an alternative the the common `@observe()` feature request.\n- Batched synchronous updates, when using a utility like []`batchedEffect()`](https://github.com/proposal-signals/signal-utils?tab=readme-ov-file#batched-effects)\n\n## Related Libraries\n\n### signal-utils\n\nThe [`signal-utils` project](https://github.com/proposal-signals/signal-utils)\ncontains a lot of utilities for building signals-based data models.\n\nSome of these are especially useful for use cases around shared observable state. The signal-backed collections (arrays, maps, and sets) can help address cases where Lit's reactive properties cannot see internal changes to objects.","users":{}}