sveltejs · Rich-Harris · May 19, 2025 · May 15, 2025 · May 15, 2025 · May 15, 2025
diff --git a/documentation/docs/03-template-syntax/[email protected] b/documentation/docs/03-template-syntax/[email protected]
@@ -2,7 +2,9 @@
 title: {@attach ...}
 ---
 
-Attachments are functions that run when an element is mounted to the DOM. Optionally, they can return a function that is called when the element is later removed from the DOM.
+Attachments are functions that run in an [effect]($effect) when an element is mounted to the DOM or when [state]($state) read inside the function updates.
+
+Optionally, they can return a function that is called before the attachment re-runs, or when the element is later removed from the DOM.
 
 > [!NOTE]
 > Attachments are available in Svelte 5.29 and newer.
@@ -55,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.
+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.
+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.
+
+In case this is not the desired behavior, and you instead want the attachment to only be executed once on mount, then make sure to not read state eagerly inside the function body. Assuming `tippy` would be very expensive to setup and tear down (which it isn't), then you could rewrite the above example by passing a reference to the `content` variable and invoke it inside a nested effect:
+
+```svelte
+<!--- file: App.svelte --->
+<script>
+	import tippy from 'tippy.js';
+	let content = $state('Hello!');
+	/**
+	 * @param {() => string} content
+	 * @returns {import('svelte/attachments').Attachment}
+	 */
+	function tooltip(content) {
+		return (element) => {
+			const tooltip = tippy(element);
+			$effect(() => {
+				tippy.setContent(content());
+			});
+			return tooltip.destroy;
+		};
+	}
+</script>
+<input bind:value={content} />
+<button {@attach tooltip(() => content)}>
+	Hover me
+</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.
+
+In case this is not the desired behavior, and you instead want the attachment to only be executed once on mount, then make sure to not read state eagerly inside the function body. Assuming `tippy` would be very expensive to setup and tear down (which it isn't), then you could rewrite the above example by passing a reference to the `content` variable and invoke it inside a nested effect:
+
+```svelte
+<!--- file: App.svelte --->
+<script>
+	import tippy from 'tippy.js';
+	let content = $state('Hello!');
+	/**
+	 * @param {() => string} content
+	 * @returns {import('svelte/attachments').Attachment}
+	 */
+	function tooltip(content) {
+		return (element) => {
+			const tooltip = tippy(element);
+			$effect(() => {
+				tippy.setContent(content());
+			});
+			return tooltip.destroy;
+		};
+	}
+</script>
+<input bind:value={content} />
+<button {@attach tooltip(() => content)}>
+	Hover me
+</button>
+```
 
 ## Inline attachments