useAniRef

This primitive applies animation styles directly to a DOM element using the use: directive, bypassing Svelte's reactivity for high performance. It also includes a built-in event manager to simplify interactive animations.

Example

<script>
  import { a } from '@freestylejs/ani-core';
  import { useAniRef } from '@freestylejs/ani-svelte';

  // 1. Define the animation structure and timeline.
  const myTimeline = a.dynamicTimeline(
    a.sequence([
      a.ani({ to: { x: 500, rotate: 360 }, duration: 1 }),
      a.ani({ to: { x: 0, rotate: 0 }, duration: 1 }),
    ])
  );

  // 2. Use the utility to get the action and controller.
  const [refAction, controller] = useAniRef({
    timeline: myTimeline,
    initialValue: { x: 0, rotate: 0 },
    // 3. Add event handlers for interactivity.
    events: {
      onMousedown: (ctx, event) => {
        // The context `ctx` contains the current animation value and the controller.
        ctx.play({ from: { x: ctx.x, rotate: ctx.rotate } });
      },
      onMouseup: (ctx) => {
        ctx.pause();
      },
    },
  });
</script>

<!-- 4. Bind the action to the element -->
<div use:refAction style="width: 100px; height: 100px; background: blue;" on:click={() => controller.play({ from: { x: 0, rotate: 0 } })} />

Usage & Concepts

Overview

The useAniRef primitive is designed for performance. It takes a configuration object (AniRefProps) and returns a Svelte Action and the timeline controller. When the action is applied to an element, it directly manipulates its styles on each animation frame, avoiding Svelte's virtual DOM overhead.

Event handlers passed to the events property receive a context object containing both the current animation value and the timeline controller, making it easy to build complex interactions.

When to Use

• Do use useAniRef for high-performance animations of CSS properties like transform and opacity.
• Do use it for complex, interactive animations driven by user input at 60fps.
• Don't use useAniRef when you need to read the animated values elsewhere in your component. Use useAni for that.

Related Components

• useAni - For reactive animations that integrate with Svelte stores.
• EventManager - The underlying utility used by the events property.