Svelte Actions: Reusable DOM Logic

Why it exists

Svelte is a declarative framework, but real-world apps sometimes need to perform imperative DOM manipulation. Instead of polluting component logic with direct DOM calls, Actions provide a clean, reusable, and Svelte-idiomatic way to encapsulate this behavior.

The mental model

An action is like a constructor for a DOM element's behavior. You attach it with use:myaction, and Svelte calls your myaction function with the element node itself, giving you a "backdoor" to manipulate it directly after it's been mounted in the DOM.

How it works

You define a function that accepts the DOM node as its first argument and optional parameters as its second. This function is called only once when the element is mounted. Inside, you use an effect (in Svelte 5) to set up your logic, like adding event listeners. The function returned from the effect is the cleanup code, which runs when the element is unmounted. Any logic that needs to react to changing parameters must be placed within this effect.

When to use it

Actions are perfect for integrating third-party vanilla JS libraries that need a DOM node (e.g., a charting or animation library). They are also great for creating reusable, self-contained behaviors like a "click outside" detector, a tooltip, or custom gesture handlers like onswipeleft.

When not to use it

Avoid actions for logic that can be accomplished with standard Svelte features like event handlers (on:click), bindings (bind:value), or component props. For newer, more composable patterns in Svelte 5.29+, the official documentation suggests considering "attachments" as a more flexible alternative.

One canonical example

A classic use case is creating a lazyload action for images. The action would receive the img node, set up an IntersectionObserver to watch when the image enters the viewport, and then swap the data-src attribute to src to trigger the download. This logic is neatly contained in the action and can be reused on any image with use:lazyload.