Animate SVG on Scroll — svg-scroll-draw API Reference

<script src="https://unpkg.com/svg-scroll-draw/dist/cdn/svg-scroll-draw.global.js"></script>

import { scrollDraw } from 'svg-scroll-draw';

const instance = scrollDraw('#hero-svg', {
  easing: 'ease-out',
  speed:  1.2,
  fade:   true,
  once:   true,
  onComplete: () => console.log('all paths drawn!'),
});

// Control playback later
instance.pause();
instance.resume();
instance.seek(0.5);   // jump to 50%
instance.replay();
instance.destroy();   // cleanup on unmount

// Default — animates across the full scroll-through
scrollDraw('#svg', { trigger: { start: 'top bottom', end: 'bottom top' } });

// Tighter window — starts later, finishes earlier
scrollDraw('#svg', { trigger: { start: 'top 60%', end: 'bottom 40%' } });

// Percentage shorthand
scrollDraw('#svg', { trigger: { start: '20%', end: '80%' } });

// Color interpolation
scrollDraw('#svg', { strokeColor: ['#ff90e8', '#ffc900'] });

// Fill flood in sync with draw (logo reveal)
scrollDraw('#logo', { fillOpacity: [0, 1], easing: 'ease-out' });

// Clip-path reveal on an image or div
scrollDraw('#image-wrapper', { clip: 'left', speed: 0.8 });

// Path morphing
scrollDraw('#shape', { morphTo: 'M10 80 Q50 10 90 80', easing: 'spring' });

scrollDraw('#svg', {
  onStart:    () => console.log('started'),
  onProgress: (p) => (label.style.opacity = p),
  onComplete: () => badge.classList.add('visible'),

  waypoints: {
    0.25: () => console.log('25% drawn'),
    0.5:  () => triggerConfetti(),
    1.0:  () => showNextSection(),
  },
});

const instance = scrollDraw('#svg', { easing: 'spring' });

// Scrubber slider
slider.addEventListener('input', (e) => {
  instance.seek(e.target.value / 100);
});

// Pause on hover
svg.addEventListener('mouseenter', () => instance.pause());
svg.addEventListener('mouseleave', () => instance.resume());

// Cleanup
window.addEventListener('unload', () => instance.destroy());

import { ScrollDraw } from 'svg-scroll-draw/react';

export function Hero() {
  return (
    <ScrollDraw
      easing="ease-out"
      speed={1.2}
      fade
      once
      stagger={0.1}
      trigger={{ start: 'top 80%', end: 'center 20%' }}
      onComplete={() => console.log('done!')}
    >
      <svg viewBox="0 0 200 100" fill="none">
        <path d="M10 50 Q100 10 190 50" stroke="black" strokeWidth="2" />
        <circle cx="100" cy="50" r="30" stroke="black" strokeWidth="2" />
      </svg>
    </ScrollDraw>
  );
}

<script setup>
import { ScrollDraw } from 'svg-scroll-draw/vue';
</script>

<template>
  <ScrollDraw easing="ease-out" :speed="1.2" fade once>
    <svg viewBox="0 0 200 100" fill="none">
      <path d="M10 50 Q100 10 190 50" stroke="black" stroke-width="2" />
    </svg>
  </ScrollDraw>
</template>

import { useScrollDraw } from 'svg-scroll-draw/vue';

// Returns a ref — attach it to your container element
const containerRef = useScrollDraw({ easing: 'spring', speed: 0.9, once: true });

<script>
  import { scrollDraw, createScrollDraw } from 'svg-scroll-draw/svelte';

  // For replay/pause control, use createScrollDraw
  const { action, getInstance } = createScrollDraw({ easing: 'ease-out', speed: 1.2 });
</script>

<!-- Simple action -->
<div use:scrollDraw={{ easing: 'spring', fade: true, once: true }}>
  <svg viewBox="0 0 200 100" fill="none">
    <path d="M10 50 Q100 10 190 50" stroke="black" stroke-width="2" />
  </svg>
</div>

<!-- With instance control -->
<div use:action>
  <svg>...</svg>
</div>
<button on:click={() => getInstance()?.replay()}>Replay</button>

import { useScrollDraw, createScrollDraw } from 'svg-scroll-draw/solid';

// Simple hook
function Hero() {
  const ref = useScrollDraw({ easing: 'ease-out', fade: true, once: true });
  return (
    <div ref={ref}>
      <svg viewBox="0 0 200 100" fill="none">
        <path d="M10 50 Q100 10 190 50" stroke="black" stroke-width="2" />
      </svg>
    </div>
  );
}

// With instance control
function HeroWithReplay() {
  const { ref, getInstance } = createScrollDraw({ easing: 'spring' });
  return (
    <>
      <div ref={ref}><svg>...</svg></div>
      <button onClick={() => getInstance()?.replay()}>Replay</button>
    </>
  );
}

import { Component, ViewChild, ElementRef, AfterViewInit, OnDestroy } from '@angular/core';
import { ScrollDrawRef } from 'svg-scroll-draw/angular';

@Component({
  selector: 'app-hero',
  template: `<div #container><svg>...</svg></div>`,
})
export class HeroComponent implements AfterViewInit, OnDestroy {
  @ViewChild('container') containerRef!: ElementRef<HTMLElement>;
  private draw = new ScrollDrawRef();

  ngAfterViewInit() {
    this.draw.init(this.containerRef.nativeElement, {
      easing: 'ease-out', speed: 1.2, fade: true, once: true,
    });
  }

  replay()      { this.draw.replay(); }
  ngOnDestroy() { this.draw.destroy(); }
}

import { ScrollAnimateRef } from 'svg-scroll-draw/angular';

@Component({
  selector: 'app-card',
  template: `<div #el>...</div>`,
})
export class CardComponent implements AfterViewInit, OnDestroy {
  @ViewChild('el') elRef!: ElementRef<HTMLElement>;
  private animate = new ScrollAnimateRef();

  ngAfterViewInit() {
    this.animate.init(this.elRef.nativeElement, {
      props: {
        opacity:   [0, 1],
        transform: ['translateY(40px)', 'translateY(0)'],
      },
      easing: 'ease-out',
      once:   true,
    });
  }

  ngOnDestroy() { this.animate.destroy(); }
}

import { ScrollCounterRef } from 'svg-scroll-draw/angular';

@Component({
  selector: 'app-stats',
  template: `<span #counter></span>`,
})
export class StatsComponent implements AfterViewInit, OnDestroy {
  @ViewChild('counter') counterRef!: ElementRef<HTMLElement>;
  private counter = new ScrollCounterRef();

  ngAfterViewInit() {
    this.counter.init(this.counterRef.nativeElement, {
      to:     1_250_000,
      format: n => '$' + Math.round(n).toLocaleString(),
      once:   true,
    });
  }

  ngOnDestroy() { this.counter.destroy(); }
}

import { ScrollTextRef } from 'svg-scroll-draw/angular';

@Component({
  selector: 'app-headline',
  template: `<h2 #headline>Animate on scroll.</h2>`,
})
export class HeadlineComponent implements AfterViewInit, OnDestroy {
  @ViewChild('headline') headlineRef!: ElementRef<HTMLElement>;
  private text = new ScrollTextRef();

  ngAfterViewInit() {
    this.text.init(this.headlineRef.nativeElement, {
      split:   'words',
      stagger: 0.05,
      from:    { opacity: 0, y: 24 },
      once:    true,
    });
  }

  ngOnDestroy() { this.text.destroy(); }
}

<script setup>
import { useScrollAnimate, useScrollText, useScrollCounter } from 'svg-scroll-draw/nuxt';

// Animate any CSS property
const card = useScrollAnimate({
  props: { opacity: [0, 1], transform: ['translateY(40px)', 'translateY(0)'] },
  easing: 'ease-out',
  once:   true,
});

// Split text and stagger animate
const headline = useScrollText({ split: 'words', stagger: 0.05, once: true });

// Animated counter
const revenue = useScrollCounter({
  to:     1_250_000,
  format: n => '$' + Math.round(n).toLocaleString(),
  once:   true,
});
</script>

<template>
  <div :ref="card">...</div>
  <h2 :ref="headline">Animate on scroll.</h2>
  <span :ref="revenue" />
</template>

<script setup>
import { ScrollAnimate, ScrollText, ScrollCounter } from 'svg-scroll-draw/nuxt';
</script>

<template>
  <ScrollAnimate :options="{ props: { opacity: [0,1] }, easing: 'ease-out', once: true }">
    <MyCard />
  </ScrollAnimate>

  <ScrollText :options="{ split: 'words', stagger: 0.05 }" tag="h2">
    Animate on scroll.
  </ScrollText>

  <ScrollCounter :to="1250000" :format="n => '$' + Math.round(n).toLocaleString()" :once="true" />
</template>

import { createScrollDrawPlugin } from 'svg-scroll-draw/nuxt';

export default defineNuxtPlugin((nuxtApp) => {
  // Registers <ScrollDraw>, <ScrollAnimate>, <ScrollCounter>,
  // <ScrollVideo>, <ScrollText> globally — no per-component imports.
  nuxtApp.vueApp.use(createScrollDrawPlugin());
});

<div
  data-scroll-draw
  data-scroll-draw-options='{"easing":"ease-out","fade":true,"once":true}'
>
  <svg viewBox="0 0 200 100" fill="none">
    <path d="M10 50 Q100 10 190 50" stroke="black" stroke-width="2" />
  </svg>
</div>

<script>
  import { initScrollDraw } from 'svg-scroll-draw/astro';
  initScrollDraw();
</script>

<div
  data-scroll-animate
  data-scroll-animate-options='{
    "props": { "opacity": [0,1], "transform": ["translateY(40px)","translateY(0)"] },
    "easing": "ease-out",
    "once": true
  }'
>
  Fades and slides in on scroll.
</div>

<script>
  import { initScrollAnimate } from 'svg-scroll-draw/astro';
  initScrollAnimate();
</script>

<h2
  data-scroll-text
  data-scroll-text-options='{"split":"words","stagger":0.05,"once":true}'
>
  Animate on scroll.
</h2>

<script>
  import { initScrollText } from 'svg-scroll-draw/astro';
  initScrollText();
</script>

<!-- Mix any combination of data-scroll-* attributes on the page -->
<div data-scroll-draw data-scroll-draw-options='{"easing":"ease-out"}'><svg>...</svg></div>
<div data-scroll-animate data-scroll-animate-options='{"props":{"opacity":[0,1]},"once":true}'>...</div>
<h2  data-scroll-text  data-scroll-text-options='{"split":"words","stagger":0.05}'>..</h2>
<span data-scroll-counter data-scroll-counter-options='{"to":50000,"once":true}'></span>

<script>
  import { initAll } from 'svg-scroll-draw/astro';
  // Initialises scrollDraw + scrollAnimate + scrollText + scrollCounter in one call
  const { draw, animate, text, counter } = initAll();
</script>

<script src="https://unpkg.com/svg-scroll-draw/dist/cdn/svg-scroll-draw.global.js"></script>

<scroll-draw easing="ease-out" speed="1.2" fade once>
  <svg viewBox="0 0 200 100" fill="none">
    <path d="M10 50 Q100 10 190 50" stroke="black" stroke-width="2" />
  </svg>
</scroll-draw>

import { scrollDraw } from 'svg-scroll-draw';

// Single element
const logo = scrollDraw('#logo', { easing: 'spring', once: true });

// Multiple elements with different configs
const chart  = scrollDraw('#chart',  { stagger: 0.08, speed: 0.8 });
const banner = scrollDraw('#banner', { clip: 'left', speed: 1.5 });

// Cleanup all on unload
window.addEventListener('unload', () => {
  [logo, chart, banner].forEach((i) => i.destroy());
});

import { scrollDrawGroup } from 'svg-scroll-draw/group';

const group = scrollDrawGroup(
  ['#hero-svg', '#logo', '#diagram'],
  { easing: 'ease-out', stagger: 0.1, once: true }
);

// All instances controlled together
group.replay();
group.pause();
group.resume();
group.destroy();

import { scrollDrawSequence } from 'svg-scroll-draw/group';

const seq = scrollDrawSequence(
  ['#step-1', '#step-2', '#step-3'],
  {
    easing:     'spring',
    onComplete: () => console.log('all steps complete'),
  }
);

seq.replay();   // restarts from step 1
seq.destroy();  // tears down all instances

import { useRef } from 'react';
import { useScrollDrawProgress } from 'svg-scroll-draw/react';

export function ParallaxSection() {
  const ref      = useRef<HTMLDivElement>(null);
  const progress = useScrollDrawProgress(ref, {
    speed:   1.2,
    easing:  'ease-out',
    trigger: { start: 'top 80%', end: 'center 20%' },
  });

  return (
    <div ref={ref}>
      <div
        style={{
          transform: `translateY(${(1 - progress) * 40}px)`,
          opacity:   progress,
        }}
      >
        <h2>Fades and slides in as you scroll</h2>
      </div>
    </div>
  );
}

// Uses animation-timeline: view() on supporting browsers
scrollDraw('#svg', { easing: 'ease-out', fade: true });

// Force JS engine regardless
scrollDraw('#svg', { native: false, easing: 'spring' });

import { scrollDraw, createSpring } from 'svg-scroll-draw';

// Gentle bounce — close to the built-in 'spring'
scrollDraw('#svg', { easing: createSpring() });

// Tight, snappy spring
scrollDraw('#svg', { easing: createSpring({ tension: 4, friction: 3 }) });

// Slow, wobbly spring
scrollDraw('#svg', { easing: createSpring({ tension: 1.5, friction: 1.2 }) });

import { scrollDraw, createBounce } from 'svg-scroll-draw';

// Named string — default params (3 bounces, decay 0.5)
scrollDraw('#svg', { easing: 'bounce' });

// Lots of quick bounces
scrollDraw('#svg', { easing: createBounce({ bounces: 5, decay: 0.35 }) });

// Two slow, deep bounces
scrollDraw('#svg', { easing: createBounce({ bounces: 2, decay: 0.7 }) });

import { scrollDraw, createElastic } from 'svg-scroll-draw';

// Named string — default params (amplitude 1, period 0.4)
scrollDraw('#svg', { easing: 'elastic' });

// Big snap, fast oscillation
scrollDraw('#svg', { easing: createElastic({ amplitude: 1.5, period: 0.3 }) });

// Subtle, slow wobble
scrollDraw('#svg', { easing: createElastic({ amplitude: 1.1, period: 0.6 }) });

import { scrollDrawTimeline } from 'svg-scroll-draw/timeline';

const instance = scrollDrawTimeline('#diagram', {
  trigger: { start: 'top 80%', end: 'bottom 20%' },
  tracks: [
    // Axes draw first
    { selector: '.axis',    from: 0,    to: 0.3,  easing: 'ease-out' },
    // Bars stagger, each with its own window
    { selector: '.bar-q1',  from: 0.1,  to: 0.45, easing: 'ease-out' },
    { selector: '.bar-q2',  from: 0.28, to: 0.58, easing: 'ease-out' },
    { selector: '.bar-q3',  from: 0.45, to: 0.75, easing: 'ease-out' },
    { selector: '.bar-q4',  from: 0.6,  to: 0.88, easing: 'ease-out' },
    // Trend line traces last
    { selector: '.trend',   from: 0.75, to: 1.0,  easing: 'spring'   },
  ],
  onComplete: () => console.log('all tracks done'),
});

instance.seek(0.5);   // jump to 50% of total range
instance.destroy();

import { scrollDraw } from 'svg-scroll-draw';

// One-liner for common patterns
scrollDraw('#logo',    { preset: 'reveal'     });
scrollDraw('#diagram', { preset: 'sketch'     });
scrollDraw('#text',    { preset: 'typewriter' });
scrollDraw('#hero',    { preset: 'cinematic'  });
scrollDraw('#icon',    { preset: 'spring'     });

// Override any preset value
scrollDraw('#logo', { preset: 'reveal', easing: 'spring' });

// Inspect presets directly
import { PRESETS } from 'svg-scroll-draw';
console.log(PRESETS.reveal);
// { easing: 'ease-out', fade: true, speed: 1.2, once: true }

npx svg-scroll-draw init

/* Drive any CSS property directly from scroll progress */
.hero-text {
  opacity: var(--scroll-draw-progress);
  transform: translateY(calc((1 - var(--scroll-draw-progress)) * 24px));
}

.highlight {
  background-size: calc(var(--scroll-draw-progress) * 100%) 100%;
}

.counter {
  /* Combine with @property for smooth transitions */
  color: oklch(from var(--scroll-draw-progress) 60% 0.2 250);
}

import { scrollDraw } from 'svg-scroll-draw';

// No onProgress callback needed —
// --scroll-draw-progress is set automatically
scrollDraw('#hero-svg', { easing: 'ease-out', once: true });

// The CSS does the rest:

<script setup>
import { useScrollAnimate } from 'svg-scroll-draw/vue';

const el = useScrollAnimate({
  props: { opacity: [0, 1], transform: ['translateY(40px)', 'translateY(0)'] },
  easing: 'ease-out',
  once: true,
});
</script>

<template>
  <div :ref="el">Animates on scroll.</div>
</template>

<!-- Or use the component wrapper: -->
<ScrollAnimate :options="{ props: { opacity: [0, 1] }, easing: 'ease-out', once: true }">
  <div>Animates on scroll.</div>
</ScrollAnimate>

<script setup>
import { useScrollCounter } from 'svg-scroll-draw/vue';

const el = useScrollCounter({
  to: 1_250_000,
  format: n => '$' + Math.round(n).toLocaleString(),
  easing: 'ease-out',
  once: true,
});
</script>

<template>
  <span :ref="el" />
</template>

<!-- Or use the component: -->
<ScrollCounter
  :to="1250000"
  :format="n => '$' + Math.round(n).toLocaleString()"
  easing="ease-out"
  :once="true"
/>

<script setup>
import { useScrollVideo } from 'svg-scroll-draw/vue';

const vid = useScrollVideo({
  trigger: { start: 'top top', end: 'bottom top' },
});
</script>

<template>
  <video :ref="vid" src="/hero.mp4" muted playsinline preload="auto" />
</template>

<!-- Or use the component: -->
<ScrollVideo
  src="/hero.mp4"
  :options="{ trigger: { start: 'top top', end: 'bottom top' } }"
/>

<script setup>
import { useScrollText } from 'svg-scroll-draw/vue';

const el = useScrollText({
  split: 'words',
  stagger: 0.05,
  from: { opacity: 0, y: 24 },
  once: true,
});
</script>

<template>
  <h2 :ref="el">Animate on scroll.</h2>
</template>

<!-- Or use the component (tag defaults to "p"): -->
<ScrollText :options="{ split: 'words', stagger: 0.05 }" tag="h2">
  Animate on scroll.
</ScrollText>

<script>
  import { scrollAnimate } from 'svg-scroll-draw/svelte';

  const opts = {
    props: { opacity: [0, 1], transform: ['translateY(40px)', 'translateY(0)'] },
    easing: 'ease-out',
    once: true,
  };
</script>

<div use:scrollAnimate={opts}>Animates on scroll.</div>

<script>
  import { scrollCounterAction } from 'svg-scroll-draw/svelte';
</script>

<span use:scrollCounterAction={{ to: 1250000, format: n => '$' + Math.round(n).toLocaleString(), once: true }} />

<script>
  import { scrollTextAction } from 'svg-scroll-draw/svelte';
</script>

<h2 use:scrollTextAction={{ split: 'words', stagger: 0.05, once: true }}>
  Animate on scroll.
</h2>

<script>
  import { createScrollAnimate } from 'svg-scroll-draw/svelte';

  const { action, getInstance } = createScrollAnimate({
    props: { opacity: [0, 1] },
    easing: 'ease-out',
    once: true,
  });
</script>

<div use:action>...</div>
<button on:click={() => getInstance()?.replay()}>Replay</button>

import { useScrollAnimate } from 'svg-scroll-draw/solid';

function Hero() {
  const ref = useScrollAnimate({
    props: { opacity: [0, 1], transform: ['translateY(40px)', 'translateY(0)'] },
    easing: 'ease-out',
    once: true,
  });
  return <div ref={ref}>Animates on scroll.</div>;
}

import { useScrollCounter } from 'svg-scroll-draw/solid';

function Revenue() {
  const ref = useScrollCounter({
    to: 1_250_000,
    format: n => '$' + Math.round(n).toLocaleString(),
    easing: 'ease-out',
    once: true,
  });
  return <span ref={ref} />;
}

import { useScrollText } from 'svg-scroll-draw/solid';

function Headline() {
  const ref = useScrollText({
    split: 'words',
    stagger: 0.05,
    from: { opacity: 0, y: 24 },
    once: true,
  });
  return <h2 ref={ref}>Animate on scroll.</h2>;
}

import { createScrollAnimate } from 'svg-scroll-draw/solid';

function Hero() {
  const { ref, getInstance } = createScrollAnimate({
    props: { opacity: [0, 1] },
    easing: 'ease-out',
    once: true,
  });
  return (
    <>
      <div ref={ref}>...</div>
      <button onClick={() => getInstance()?.replay()}>Replay</button>
    </>
  );
}

import { scrollProgress } from 'svg-scroll-draw/progress';

// Set --scroll-progress (raw) and --scroll-progress-eased on the element
scrollProgress('#hero', { easing: 'ease-in-out' });

// Custom variable names
scrollProgress('#section', {
  variable:      '--my-progress',
  easedVariable: '--my-progress-eased',
  trigger: { start: 'top 80%', end: 'bottom 20%' },
});

// Use in CSS
// #hero {
//   opacity: calc(var(--scroll-progress-eased));
//   transform: translateY(
//     calc((1 - var(--scroll-progress-eased)) * 40px)
//   );
// }

import { scrollHorizontal } from 'svg-scroll-draw/horizontal';

// Minimal CSS:
// .outer  { height: 400vh; }
// .sticky { position: sticky; top: 0; height: 100vh; overflow: hidden; }
// .track  { display: flex; width: max-content; }

const inst = scrollHorizontal('.track', {
  distance: window.innerWidth * 3,  // total horizontal travel
  easing:   'linear',               // scrub feel
  trigger: {
    start: 'top top',
    end:   'bottom bottom',
  },
  onProgress: (p) => dots.setActive(Math.round(p * 3)),
});

// React
useEffect(() => {
  const inst = scrollHorizontal(trackRef.current, {
    distance: trackRef.current.scrollWidth - window.innerWidth,
  });
  return () => inst.destroy();
}, []);

inst.refresh();  // recalculate after layout change
inst.destroy();  // cleanup

import { scrollReveal } from 'svg-scroll-draw/reveal';

// Default: fade up
scrollReveal('.card');

// Named preset
scrollReveal('.feature', { preset: 'scale' });

// Custom from state
scrollReveal('.item', {
  from:    { opacity: 0, y: 40, scale: 0.95 },
  stagger: 0.1,
  easing:  'ease-out',
  once:    true,
});

// Presets: 'fadeUp' | 'fadeDown' | 'fadeLeft' | 'fadeRight' | 'scale' | 'flip' | 'flipX'

// Cleanup
const instance = scrollReveal('.card', { preset: 'fadeUp' });
instance.destroy();

import { scrollAnimate } from 'svg-scroll-draw';

// Default sensitivity (1) — moderate speed-up on fast scroll
scrollAnimate('#hero', {
  props: { opacity: [0, 1], transform: ['translateY(32px)', 'translateY(0)'] },
  velocityScale: true,
});

// High sensitivity (3) — very responsive to scroll speed
scrollAnimate('#kinetic-bg', {
  props: { transform: ['translateY(0px)', 'translateY(-200px)'] },
  velocityScale: 3,
  easing: 'linear',
});

// velocityScale is available on scrollDraw too:
scrollDraw('#logo', {
  easing:        'ease-out',
  velocityScale: 1.5,
});

import { scrollPin } from 'svg-scroll-draw/pin';

// Pin at top of viewport for one viewport-height of scroll
const pin = scrollPin('#panel', {
  pinDistance: window.innerHeight,
  onEnter:     () => panel.classList.add('active'),
  onLeave:     () => panel.classList.remove('active'),
  onEnterBack: () => panel.classList.add('active'),
  onLeaveBack: () => panel.classList.remove('active'),
  onProgress:  (p) => console.log('progress', p), // 0–1 through pin zone
});

// Apple-style: pin image, scroll text past it
scrollPin('#product-image', {
  top:         80,    // pin 80px from viewport top (below a fixed nav)
  pinDistance: 800,   // hold for 800px of scroll
});

// Recalculate after layout change (accordion, dynamic content)
pin.refresh();

// Remove on unmount / route change
pin.destroy();

import { scrollSnap } from 'svg-scroll-draw/snap';

// Basic vertical snap between fullscreen sections
const snap = scrollSnap('.section', {
  duration:  600,
  easing:    'ease-in-out',
  threshold: 0.3,           // snap forward if user scrolled >30% of a section
  onSnap:    (index) => console.log('snapped to section', index),
});

// Horizontal snap (e.g. feature carousel)
scrollSnap('.card', {
  direction: 'horizontal',
  duration:  400,
  easing:    'ease-out',
  onSnap:    (i) => setActiveCard(i),
});

// Programmatic control
snap.snapTo(2);          // scroll to section index 2
snap.getCurrentIndex();  // → current snapped index

// Cleanup
snap.destroy();

import { scrollAnimate } from 'svg-scroll-draw';

// Activate/deactivate a section as it enters and leaves view
scrollAnimate('#feature-section', {
  props: { opacity: [0.4, 1] },
  trigger: { start: 'top center', end: 'bottom center' },
  onEnter:     () => nav.setActive('feature'),   // scrolling down, entering
  onLeave:     () => nav.clearActive('feature'),  // scrolling down, leaving
  onEnterBack: () => nav.setActive('feature'),   // scrolling up, re-entering
  onLeaveBack: () => nav.clearActive('feature'),  // scrolling up, leaving from top
});

// Lazy-load an image when it first enters view
scrollAnimate('#hero-img', {
  props: { opacity: [0, 1] },
  once: true,
  onEnter: () => {
    document.querySelector('#hero-img')
      .setAttribute('src', '/hero.webp');
  },
});

import Lenis from '@studio-freight/lenis'; // Lenis v1
import { createLenisAdapter } from 'svg-scroll-draw/lenis';
import { scrollAnimate } from 'svg-scroll-draw';

// 1. Create Lenis
const lenis = new Lenis({ duration: 1.2, easing: t => Math.min(1, 1.001 - Math.pow(2, -10 * t)) });

// 2. Patch window.scrollY so all svg-scroll-draw engines read the virtual scroll
const adapter = createLenisAdapter(lenis);

// 3. Use svg-scroll-draw as normal
scrollAnimate('#hero', {
  props: { opacity: [0, 1], transform: ['translateY(40px)', 'translateY(0)'] },
  once: true,
});

// 4. Drive Lenis with rAF
function raf(time) {
  lenis.raf(time);
  requestAnimationFrame(raf);
}
requestAnimationFrame(raf);

// 5. Cleanup
adapter.destroy();
lenis.destroy();

// ── Lenis v2 (no adapter needed) ──────────────────────────────────
import Lenis from 'lenis'; // v2 patches window.scrollY natively

const lenis = new Lenis();
lenis.on('scroll', ScrollTrigger.update); // optional if mixing with other libs

// svg-scroll-draw just works
scrollAnimate('#hero', { props: { opacity: [0, 1] }, once: true });

import { scrollAnimate } from 'svg-scroll-draw';

// Fade + slide in
scrollAnimate('#hero-text', {
  props: {
    opacity:   [0, 1],
    transform: ['translateY(40px)', 'translateY(0px)'],
  },
  easing: 'ease-out',
  once: true,
});

// Color transition
scrollAnimate('#section', {
  props: {
    backgroundColor: ['#ffffff', '#0d0d0d'],
    color:           ['#000000', '#ffffff'],
  },
});

// React wrapper
import { ScrollAnimate } from 'svg-scroll-draw/react';

<ScrollAnimate
  props={{ opacity: [0, 1], transform: ['translateY(24px)', 'translateY(0)'] }}
  easing="ease-out"
  once
>
  <div>Any content</div>
</ScrollAnimate>

import { scrollCounter } from 'svg-scroll-draw';

// Simple counter
scrollCounter('#user-count', { to: 50000 });

// Formatted with locale
scrollCounter('#revenue', {
  to:     1_250_000,
  format: n => '$' + Math.round(n).toLocaleString(),
  easing: 'ease-out',
  once:   true,
});

// Percentage with decimal
scrollCounter('#conversion', {
  from:     0,
  to:       94.7,
  decimals: 1,
  format:   n => n.toFixed(1) + '%',
});

// React
import { ScrollCounter } from 'svg-scroll-draw/react';
<ScrollCounter to={50000} format={n => n.toLocaleString()} once />

import { scrollParallax } from 'svg-scroll-draw';

scrollParallax('#hero-bg-image', { speed: 0.4 });
scrollParallax('#floating-element', { speed: -0.2 }); // moves opposite
scrollParallax('#side-badge', { speed: 0.3, axis: 'x' }); // horizontal

import { scrollVideo } from 'svg-scroll-draw/video';

// Full scrub — plays as user scrolls through section
scrollVideo('#hero-video', {
  trigger: { start: 'top top', end: 'bottom top' },
});

// Scrub only the first 3 seconds
scrollVideo('#product-reveal', {
  from:    0,
  to:      3,
  trigger: { start: 'top 80%', end: 'top 20%' },
  easing:  'ease-in-out',
});

// React
import { ScrollVideo } from 'svg-scroll-draw/react';
<ScrollVideo src="/hero.mp4" trigger={{ start: 'top top', end: 'bottom top' }} />

import { scrollText } from 'svg-scroll-draw/text';

// Words fade up one by one
scrollText('#headline', {
  split:   'words',
  stagger: 0.05,
  from:    { opacity: 0, y: 24 },
  easing:  'ease-out',
  once:    true,
});

// Characters with rotation
scrollText('#tagline', {
  split:   'chars',
  stagger: 0.025,
  from:    { opacity: 0, y: 32, rotate: 8 },
  once:    true,
});

// React
import { ScrollText } from 'svg-scroll-draw/react';
<ScrollText split="words" stagger={0.05} from={{ opacity: 0, y: 24 }} once>
  Animate this headline.
</ScrollText>

import { devtools } from 'svg-scroll-draw/devtools';

// Enable once — instruments all active instances
devtools.enable();

// Keyboard shortcut: Cmd+Shift+S / Ctrl+Shift+S to toggle
// Or toggle programmatically:
devtools.toggle();

// Highlight a specific element for 2 seconds
devtools.highlight('#my-animated-element');

import type {
  ScrollDrawOptions,
  ScrollDrawInstance,
  EasingName,
  TriggerConfig,
} from 'svg-scroll-draw';

type EasingName = 'linear' | 'ease-in' | 'ease-out' | 'ease-in-out' | 'spring';

interface TriggerConfig {
  start?: string;
  end?:   string;
}

interface ScrollDrawInstance {
  destroy:     () => void;
  replay:      () => void;
  pause:       () => void;
  resume:      () => void;
  seek:        (progress: number) => void;
  getProgress: () => number;
}

interface ScrollDrawOptions {
  selector?:        string;
  speed?:           number;
  fade?:            boolean;
  easing?:          EasingName | ((t: number) => number);
  trigger?:         TriggerConfig;
  stagger?:         number;
  direction?:       'forward' | 'reverse';
  once?:            boolean;
  debug?:           boolean;
  axis?:            'x' | 'y';
  scrollContainer?: string | Element;
  autoReverse?:     boolean;
  delay?:           number;
  strokeColor?:     string | [string, string];
  strokeWidth?:     number | [number, number];
  fillOpacity?:     number | [number, number];
  clip?:            boolean | 'left' | 'right' | 'top' | 'bottom' | 'center';
  waypoints?:       Record<number, () => void>;
  velocityScale?:   boolean | number;
  threshold?:       number;
  rootMargin?:      string;
  repeat?:          number | 'infinite';
  repeatDelay?:     number;
  morphTo?:         string;
  onProgress?:      (alpha: number) => void;
  onStart?:         () => void;
  onComplete?:      () => void;
  native?:          boolean;
}