From 44bed10eae195939c30a702dcbd15b3a455567b8 Mon Sep 17 00:00:00 2001 From: Ken Kunz Date: Sun, 30 Nov 2025 11:23:46 -0600 Subject: [PATCH 1/7] docs: rename action tutorial files -> attachments --- .../01-attach}/+assets/app-a/src/lib/App.svelte | 0 .../01-attach}/+assets/app-a/src/lib/Canvas.svelte | 0 .../+assets/app-a/src/lib/attachments.svelte.js} | 0 .../01-attach}/+assets/app-b/src/lib/App.svelte | 2 +- .../+assets/app-b/src/lib/attachments.svelte.js} | 0 .../01-actions => 08-attachments/01-attach}/index.md | 12 ++++++------ .../+assets/app-a/package.json | 0 .../+assets/app-a/src/lib/App.svelte | 0 .../+assets/app-b/src/lib/App.svelte | 0 .../02-attachment-factories}/index.md | 2 +- .../{08-actions => 08-attachments}/index.md | 2 +- 11 files changed, 9 insertions(+), 9 deletions(-) rename apps/svelte.dev/content/tutorial/01-svelte/{08-actions/01-actions => 08-attachments/01-attach}/+assets/app-a/src/lib/App.svelte (100%) rename apps/svelte.dev/content/tutorial/01-svelte/{08-actions/01-actions => 08-attachments/01-attach}/+assets/app-a/src/lib/Canvas.svelte (100%) rename apps/svelte.dev/content/tutorial/01-svelte/{08-actions/01-actions/+assets/app-a/src/lib/actions.svelte.js => 08-attachments/01-attach/+assets/app-a/src/lib/attachments.svelte.js} (100%) rename apps/svelte.dev/content/tutorial/01-svelte/{08-actions/01-actions => 08-attachments/01-attach}/+assets/app-b/src/lib/App.svelte (97%) rename apps/svelte.dev/content/tutorial/01-svelte/{08-actions/01-actions/+assets/app-b/src/lib/actions.svelte.js => 08-attachments/01-attach/+assets/app-b/src/lib/attachments.svelte.js} (100%) rename apps/svelte.dev/content/tutorial/01-svelte/{08-actions/01-actions => 08-attachments/01-attach}/index.md (75%) rename apps/svelte.dev/content/tutorial/01-svelte/{08-actions/02-adding-parameters-to-actions => 08-attachments/02-attachment-factories}/+assets/app-a/package.json (100%) rename apps/svelte.dev/content/tutorial/01-svelte/{08-actions/02-adding-parameters-to-actions => 08-attachments/02-attachment-factories}/+assets/app-a/src/lib/App.svelte (100%) rename apps/svelte.dev/content/tutorial/01-svelte/{08-actions/02-adding-parameters-to-actions => 08-attachments/02-attachment-factories}/+assets/app-b/src/lib/App.svelte (100%) rename apps/svelte.dev/content/tutorial/01-svelte/{08-actions/02-adding-parameters-to-actions => 08-attachments/02-attachment-factories}/index.md (97%) rename apps/svelte.dev/content/tutorial/01-svelte/{08-actions => 08-attachments}/index.md (81%) diff --git a/apps/svelte.dev/content/tutorial/01-svelte/08-actions/01-actions/+assets/app-a/src/lib/App.svelte b/apps/svelte.dev/content/tutorial/01-svelte/08-attachments/01-attach/+assets/app-a/src/lib/App.svelte similarity index 100% rename from apps/svelte.dev/content/tutorial/01-svelte/08-actions/01-actions/+assets/app-a/src/lib/App.svelte rename to apps/svelte.dev/content/tutorial/01-svelte/08-attachments/01-attach/+assets/app-a/src/lib/App.svelte diff --git a/apps/svelte.dev/content/tutorial/01-svelte/08-actions/01-actions/+assets/app-a/src/lib/Canvas.svelte b/apps/svelte.dev/content/tutorial/01-svelte/08-attachments/01-attach/+assets/app-a/src/lib/Canvas.svelte similarity index 100% rename from apps/svelte.dev/content/tutorial/01-svelte/08-actions/01-actions/+assets/app-a/src/lib/Canvas.svelte rename to apps/svelte.dev/content/tutorial/01-svelte/08-attachments/01-attach/+assets/app-a/src/lib/Canvas.svelte diff --git a/apps/svelte.dev/content/tutorial/01-svelte/08-actions/01-actions/+assets/app-a/src/lib/actions.svelte.js b/apps/svelte.dev/content/tutorial/01-svelte/08-attachments/01-attach/+assets/app-a/src/lib/attachments.svelte.js similarity index 100% rename from apps/svelte.dev/content/tutorial/01-svelte/08-actions/01-actions/+assets/app-a/src/lib/actions.svelte.js rename to apps/svelte.dev/content/tutorial/01-svelte/08-attachments/01-attach/+assets/app-a/src/lib/attachments.svelte.js diff --git a/apps/svelte.dev/content/tutorial/01-svelte/08-actions/01-actions/+assets/app-b/src/lib/App.svelte b/apps/svelte.dev/content/tutorial/01-svelte/08-attachments/01-attach/+assets/app-b/src/lib/App.svelte similarity index 97% rename from apps/svelte.dev/content/tutorial/01-svelte/08-actions/01-actions/+assets/app-b/src/lib/App.svelte rename to apps/svelte.dev/content/tutorial/01-svelte/08-attachments/01-attach/+assets/app-b/src/lib/App.svelte index 81c8f1a686..e600f4957c 100644 --- a/apps/svelte.dev/content/tutorial/01-svelte/08-actions/01-actions/+assets/app-b/src/lib/App.svelte +++ b/apps/svelte.dev/content/tutorial/01-svelte/08-attachments/01-attach/+assets/app-b/src/lib/App.svelte @@ -1,6 +1,6 @@ ``` -...then add it to the menu with the `use:` directive: +...then add it to the menu with the `{@attach}` tag: ```svelte /// file: App.svelte -
+
``` -Let's take a look at the `trapFocus` function in `attachments.svelte.js`. An action function is called with a `node` — the `
` in our case — when the node is mounted to the DOM. Inside the action, we have an [effect](effects). +Let's take a look at the `trapFocus` function in `attachments.svelte.js`. An attachment function is called with a `node` — the `
` in our case — when the node is mounted to the DOM. Attachments run inside an [effect](effects), so they re-run whenever any state read inside the function changes. First, we need to add an event listener that intercepts Tab key presses: @@ -42,20 +42,22 @@ First, we need to add an event listener that intercepts Tab key presses: /// file: attachments.svelte.js $effect(() => { focusable()[0]?.focus(); - +++node.addEventListener('keydown', handleKeydown);+++ + +++const off = on(node, 'keydown', handleKeydown);+++ }); ``` -Second, we need to do some cleanup when the node is unmounted — removing the event listener, and restoring focus to where it was before the element mounted: +> [!NOTE] [`on`](/docs/svelte/svelte-events#on) is a wrapper around `addEventListener` that uses event delegation. It returns a function that removes the handler. + +Second, we need to do some cleanup when the node is unmounted — removing the event listener, and restoring focus to where it was before the element mounted. As with effects, an attachment can return a teardown function, which runs immediately before the attachment re-runs or after the element is removed from the DOM: ```js /// file: attachments.svelte.js $effect(() => { focusable()[0]?.focus(); - node.addEventListener('keydown', handleKeydown); + const off = on(node, 'keydown', handleKeydown); +++ return () => { - node.removeEventListener('keydown', handleKeydown); + off(); previous?.focus(); };+++ }); From a204be157733312ece8e626b8f02da19ed4f4c5f Mon Sep 17 00:00:00 2001 From: Ken Kunz Date: Sun, 30 Nov 2025 19:05:19 -0600 Subject: [PATCH 3/7] docs: update "Attachment factories" tutorial step --- .../+assets/app-a/src/lib/App.svelte | 9 ++--- .../+assets/app-b/src/lib/App.svelte | 11 +++---- .../02-attachment-factories/index.md | 33 ++++++++++++------- 3 files changed, 29 insertions(+), 24 deletions(-) diff --git a/apps/svelte.dev/content/tutorial/01-svelte/08-attachments/02-attachment-factories/+assets/app-a/src/lib/App.svelte b/apps/svelte.dev/content/tutorial/01-svelte/08-attachments/02-attachment-factories/+assets/app-a/src/lib/App.svelte index 7f939dbe4a..b5c473571a 100644 --- a/apps/svelte.dev/content/tutorial/01-svelte/08-attachments/02-attachment-factories/+assets/app-a/src/lib/App.svelte +++ b/apps/svelte.dev/content/tutorial/01-svelte/08-attachments/02-attachment-factories/+assets/app-a/src/lib/App.svelte @@ -4,17 +4,14 @@ let content = $state('Hello!'); function tooltip(node) { - $effect(() => { - const tooltip = tippy(node); - - return tooltip.destroy; - }); + const tooltip = tippy(node); + return tooltip.destroy; } - diff --git a/apps/svelte.dev/content/tutorial/01-svelte/08-attachments/02-attachment-factories/+assets/app-b/src/lib/App.svelte b/apps/svelte.dev/content/tutorial/01-svelte/08-attachments/02-attachment-factories/+assets/app-b/src/lib/App.svelte index 6653b4af89..51e4198424 100644 --- a/apps/svelte.dev/content/tutorial/01-svelte/08-attachments/02-attachment-factories/+assets/app-b/src/lib/App.svelte +++ b/apps/svelte.dev/content/tutorial/01-svelte/08-attachments/02-attachment-factories/+assets/app-b/src/lib/App.svelte @@ -3,18 +3,17 @@ let content = $state('Hello!'); - function tooltip(node, fn) { - $effect(() => { - const tooltip = tippy(node, fn()); - + function tooltip(content) { + return (node) => { + const tooltip = tippy(node, { content }); return tooltip.destroy; - }); + } } - diff --git a/apps/svelte.dev/content/tutorial/01-svelte/08-attachments/02-attachment-factories/index.md b/apps/svelte.dev/content/tutorial/01-svelte/08-attachments/02-attachment-factories/index.md index 48fec18531..401f647770 100644 --- a/apps/svelte.dev/content/tutorial/01-svelte/08-attachments/02-attachment-factories/index.md +++ b/apps/svelte.dev/content/tutorial/01-svelte/08-attachments/02-attachment-factories/index.md @@ -2,32 +2,41 @@ title: Attachment factories --- -Like transitions and animations, an action can take an argument, which the action function will be called with alongside the element it belongs to. +Often, you need an attachment to depend on some parameters or component state. In this scenario, you can use an [attachment factory](/docs/svelte/@attach#Attachment-factories) — a function that _returns_ an attachment. -In this exercise, we want to add a tooltip to the ` ``` - -> [!NOTE] In Svelte 4, actions returned an object with `update` and `destroy` methods. This still works but we recommend using `$effect` instead, as it provides more flexibility and granularity. From ab60f509f45ffd6a9880391ab629c7a3f6222ee1 Mon Sep 17 00:00:00 2001 From: Ken Kunz Date: Sun, 30 Nov 2025 20:05:18 -0600 Subject: [PATCH 4/7] docs: update "Binding to component instances" link and example Previously referenced the Actions tutorial example; updated to reference the new Attachments example. --- .../+assets/app-a/src/lib/App.svelte | 4 ++-- .../{actions.svelte.js => attachments.svelte.js} | 16 ++++++++-------- .../+assets/app-b/src/lib/App.svelte | 4 ++-- .../07-component-this/index.md | 2 +- 4 files changed, 13 insertions(+), 13 deletions(-) rename apps/svelte.dev/content/tutorial/02-advanced-svelte/04-advanced-bindings/07-component-this/+assets/app-a/src/lib/{actions.svelte.js => attachments.svelte.js} (75%) diff --git a/apps/svelte.dev/content/tutorial/02-advanced-svelte/04-advanced-bindings/07-component-this/+assets/app-a/src/lib/App.svelte b/apps/svelte.dev/content/tutorial/02-advanced-svelte/04-advanced-bindings/07-component-this/+assets/app-a/src/lib/App.svelte index 81c8f1a686..fb091dc49c 100644 --- a/apps/svelte.dev/content/tutorial/02-advanced-svelte/04-advanced-bindings/07-component-this/+assets/app-a/src/lib/App.svelte +++ b/apps/svelte.dev/content/tutorial/02-advanced-svelte/04-advanced-bindings/07-component-this/+assets/app-a/src/lib/App.svelte @@ -1,6 +1,6 @@ diff --git a/apps/svelte.dev/content/tutorial/01-svelte/08-attachments/02-attachment-factories/index.md b/apps/svelte.dev/content/tutorial/01-svelte/08-attachments/02-attachment-factories/index.md index 401f647770..2aac3bdb8c 100644 --- a/apps/svelte.dev/content/tutorial/01-svelte/08-attachments/02-attachment-factories/index.md +++ b/apps/svelte.dev/content/tutorial/01-svelte/08-attachments/02-attachment-factories/index.md @@ -14,7 +14,7 @@ function tooltip(---node---) { +++ return (node) => {+++ const tooltip = tippy(node); return tooltip.destroy; -+++ }+++ ++++ };+++ } ``` @@ -26,7 +26,7 @@ function tooltip(+++content+++) { return (node) => { const tooltip = tippy(node+++, { content }+++); return tooltip.destroy; - } + }; } ``` From ed5abbea743289bd874e430d371e450bfdada719 Mon Sep 17 00:00:00 2001 From: Ken Kunz Date: Mon, 1 Dec 2025 11:33:21 -0600 Subject: [PATCH 7/7] Update apps/svelte.dev/content/tutorial/01-svelte/08-attachments/01-attach/index.md Co-authored-by: Rich Harris --- .../tutorial/01-svelte/08-attachments/01-attach/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/svelte.dev/content/tutorial/01-svelte/08-attachments/01-attach/index.md b/apps/svelte.dev/content/tutorial/01-svelte/08-attachments/01-attach/index.md index 84d04588f2..c7b3a93ee6 100644 --- a/apps/svelte.dev/content/tutorial/01-svelte/08-attachments/01-attach/index.md +++ b/apps/svelte.dev/content/tutorial/01-svelte/08-attachments/01-attach/index.md @@ -44,7 +44,7 @@ focusable()[0]?.focus(); +++const off = on(node, 'keydown', handleKeydown);+++ ``` -> [!NOTE] [`on`](/docs/svelte/svelte-events#on) is a wrapper around `addEventListener` that uses event delegation. It returns a function that removes the handler. +> [!NOTE] [`on`](/docs/svelte/svelte-events#on) is a wrapper around `addEventListener` that uses event delegation. It returns a function that removes the handler. Second, we need to do some cleanup when the node is unmounted — removing the event listener, and restoring focus to where it was before the element mounted. As with effects, an attachment can return a teardown function, which runs immediately before the attachment re-runs or after the element is removed from the DOM: