Svelte Actions

An action attaches extra behavior directly onto an HTML element, useful for tasks that regular Svelte features cannot handle cleanly. An action runs the moment its element appears and can clean up after itself the moment that element disappears.

Why Actions Matter

Some behaviors need direct access to a raw DOM element, such as detecting a click anywhere outside a specific box or setting up a third-party library on a specific node. Actions give you a clean, reusable way to attach this kind of behavior without repeating the same setup code across many components.

Creating A Basic Action

<script>
  function highlight(node) {
    node.style.backgroundColor = "yellow";

    return {
      destroy() {
        node.style.backgroundColor = "";
      }
    };
  }
</script>

<p use:highlight>This text gets highlighted</p>

The use:highlight directive runs the highlight function, passing in the actual paragraph element as node. The function immediately sets a background color, and the returned destroy method removes that color if the paragraph ever leaves the page.

Action Lifecycle Diagram

Element appears on the page
        |
        v
Action function runs, receives the element
        |
        v
Element stays on the page, action stays active
        |
        v
Element about to be removed
        |
        v
destroy() runs, cleaning up the action's effects

Passing Parameters To An Action

<script>
  function highlight(node, color) {
    node.style.backgroundColor = color;

    return {
      destroy() {
        node.style.backgroundColor = "";
      }
    };
  }
</script>

<p use:highlight={"lightgreen"}>Highlighted in green</p>

The value inside curly braces after use:highlight becomes the second argument passed to the function, letting each element customize the action's behavior.

An Action For Detecting Outside Clicks

<script>
  function clickOutside(node, callback) {
    function handleClick(event) {
      if (!node.contains(event.target)) {
        callback();
      }
    }

    document.addEventListener("click", handleClick);

    return {
      destroy() {
        document.removeEventListener("click", handleClick);
      }
    };
  }
</script>

<div use:clickOutside={() => alert("Clicked outside")}>
  Click anywhere outside this box
</div>

The action listens for clicks across the whole document, then checks whether the click landed inside its own element. A click outside the box triggers the callback, useful for closing menus or dialogs automatically.

Common Use Cases

• Detecting clicks outside a dropdown menu or modal window
• Connecting a third-party library, such as a chart tool, to a specific element
• Adding drag-and-drop behavior to an element
• Tracking how long an element stays visible on screen

Updating An Action When Its Parameter Changes

An action can react to a changing parameter by returning an update method alongside destroy, letting it adjust its behavior without a full teardown and rebuild.

<script>
  function highlight(node, color) {
    node.style.backgroundColor = color;

    return {
      update(newColor) {
        node.style.backgroundColor = newColor;
      },
      destroy() {
        node.style.backgroundColor = "";
      }
    };
  }
</script>

Svelte calls update automatically whenever the parameter passed to the action changes, keeping the action's effect current without recreating it from scratch each time.

Key Points

• An action attaches custom behavior directly to an HTML element
• The use: directive connects an action function to an element
• A returned destroy method cleans up the action when the element disappears
• Actions can accept parameters for customizable behavior