From 49c8582770c787b5f8136aab0c6ed5d523ba1f52 Mon Sep 17 00:00:00 2001
From: Rich Harris <rich.harris@vercel.com>
Date: Mon, 19 May 2025 16:11:55 -0400
Subject: [PATCH] update docs

---
 .../docs/03-template-syntax/09-@attach.md     | 29 ++++++++++++++++++-
 1 file changed, 28 insertions(+), 1 deletion(-)

diff --git a/documentation/docs/03-template-syntax/09-@attach.md b/documentation/docs/03-template-syntax/09-@attach.md
index f799243304..2a856d45ce 100644
--- a/documentation/docs/03-template-syntax/09-@attach.md
+++ b/documentation/docs/03-template-syntax/09-@attach.md
@@ -57,7 +57,7 @@ A useful pattern is for a function, such as `tooltip` in this example, to _retur
 </button>
 ```
 
-Since the `tooltip(content)` expression runs inside an [effect]($effect), the attachment will be destroyed and recreated whenever `content` changes. The same thing would happen for any state read _inside_ the attachment function when it first runs.
+Since the `tooltip(content)` expression runs inside an [effect]($effect), the attachment will be destroyed and recreated whenever `content` changes. The same thing would happen for any state read _inside_ the attachment function when it first runs. (If this isn't what you want, see [Controlling when attachments re-run](#Controlling-when-attachments-re-run).)
 
 ## Inline attachments
 
@@ -128,6 +128,33 @@ This allows you to create _wrapper components_ that augment elements ([demo](/pl
 </Button>
 ```
 
+## Controlling when attachments re-run
+
+Attachments, unlike [actions](use), are fully reactive: `{@attach foo(bar)}` will re-run on changes to `foo` _or_ `bar` (or any state read inside `foo`):
+
+```js
+function foo(bar) {
+	return (node) => {
+		veryExpensiveSetupWork(node);
+		update(node, bar);
+	};
+}
+```
+
+In the rare case that this is a problem (for example, if `foo` does expensive and unavoidable setup work) consider passing the data inside a function and reading it in a child effect:
+
+```js
+function foo(+++getBar+++) {
+	return (node) => {
+		veryExpensiveSetupWork(node);
+
++++		$effect(() => {
+			update(node, getBar());
+		});+++
+	}
+}
+```
+
 ## Creating attachments programmatically
 
 To add attachments to an object that will be spread onto a component or element, use [`createAttachmentKey`](svelte-attachments#createAttachmentKey).