Scroll-driven Page-building Effect with Animated Cursors – cursor-swarm.js

cursor-swarm.js is a dependency-free JavaScript library that animates cursors building a web page as visitors scroll.

It draws boxes, types text, and reveals media on existing pages, with an optional reverse animation when visitors scroll up.

Features

• 5 build animations for boxes, controls, headings, body text, and media.
• Agent cursors share layout, typing, and media tasks.
• A progress HUD, cursor labels, guide lines, and completion particles.
• Optional copy-paste animations for repeated cards and UI elements.
• Optional relocation animations that move elements into position.
• Adaptive animation speed for rapid scrolling.
• Per-element animation overrides through HTML attributes.
• Built-in support for reduced-motion preferences.

How To Use It

Basic Usage

Place the core JavaScript before the closing body tag. By default, CursorSwarm scans document.body and animates elements as they enter the viewport.

<script src="cursor-swarm.js"></script>
<script>
  const swarm = new CursorSwarm({ cursors: 3 }).init();
</script>

Animate Only One Section

Set root to a section selector to animate part of the page. Add data-cs-ignore to elements that should be excluded.

<section id="feature-showcase">
  <h2>Build better workflows</h2>
  <p>Organize projects and share updates from one workspace.</p>
  <div style="padding: 24px; background: #f1f5f9; border: 1px solid #cbd5e1;">
    <h3>Project overview</h3>
    <p>Track the work that matters.</p>
  </div>
  <button type="button" data-cs-ignore>Keep this control static</button>
</section>
<script src="cursor-swarm.js"></script>
<script>
  const swarm = new CursorSwarm({
    root: '#feature-showcase',
    cursors: 3,
    palette: 'ocean',
    deconstruct: false
  }).init();
</script>

Initialize With HTML Attributes

For automatic initialization, load cursor-swarm. js in <head> with data-auto. The script hides the page until the cursors are prepared and exposes the instance as window.cursorSwarm.

<script src="cursor-swarm.js"
        data-auto
        data-cursors="4"
        data-palette="neon"
        data-start-position="corners"
        data-exit-after-build="home"></script>

For manual initialization from <head>, call CursorSwarm.cloak() immediately and initialize on DOMContentLoaded to prevent the original content from flashing:

<script src="cursor-swarm.js"></script>
<script>
  CursorSwarm.cloak();
  document.addEventListener('DOMContentLoaded', () => {
    window.cursorSwarm = new CursorSwarm().init();
  });
</script>

Customize Cursor Colors and Movement

CursorSwarm includes default, neon, pastel, sunset, ocean, forest, candy, mono, and ink palettes. You can register a palette to use your own colors. copyPaste and relocation accept true or a probability from 0 to 1.

CursorSwarm.palettes.cssscript = {
  colors: ['#2a6bf2', '#f25a72', '#16a085']
};
const swarm = new CursorSwarm({
  cursors: 3,
  palette: 'cssscript',
  startPosition: 'outside',
  copyPaste: 0.5,
  relocation: 0.3,
  exitAfterBuild: 'home'
}).init();

Control Build Types in HTML

CursorSwarm assigns a build type to each HTML element. Override it with data-cs. For media, set data-cs-dir to l, r, or t to control the scan direction. data-cs-copy and data-cs-relocate override the corresponding global options.

<h2 data-cs="type">A heading built by cursors</h2>
<p data-cs="words" data-cs-label="intro">This paragraph is revealed one word at a time.</p>
<img src="preview.jpg" alt="Product preview" data-cs="media" data-cs-dir="t">
<div data-cs="none"><p>Animate the children, not this container.</p></div>
<div data-cs="skip">Leave this element and its children unchanged.</div>

All Configuration Options

Pass an options object to new CursorSwarm(options) to configure the animation.

Cursors and Scope

Animation Behavior

Cursor Overlays and Callbacks

Public Methods and Properties

Static API

Events

Register listeners before calling init() to capture the initial start event.

const swarm = new CursorSwarm({ root: '#feature-showcase' });
swarm.on('build', (element, type, agentName) => {
  console.log(agentName, type, element);
});
swarm.on('done', () => {
  console.log('Page build complete');
});
swarm.init();

HTML Attribute Supported

Alternatives and Related Resources

• 25+ CSS Scroll/Reveal/Loading/Typing Animations for the Web – CSS Animation
• Performance-First Scroll Animation Library – WavBlock
• Text Reveal Animations On Scroll – Textify.js