v1.5.4 GitHub ↗

Dokumentasi

CursAnimation

Library custom cursor dan animasi rebuild on scroll tanpa dependency. Kursor, swarm, trail, partikel, magnetik, klik, reveal, dan efek membangun elemen seperti di Swarm.

1.5.4Versi stabil
0Dependency
UMD + ESMFormat build
MITLisensi

Instalasi

Ada dua cara: CDN untuk HTML statis, atau package untuk project dengan bundler. Stylesheet wajib dimuat — tanpa CSS, overlay tidak akan tampil.

CDN (tanpa build)

Muat CSS di <head> dan JavaScript sebelum konfigurasi. Ganti versi secara eksplisit agar stabil.

<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/rexxzyid/cursanimation@1.5.4/dist/cursanimation.min.css">
<script src="https://cdn.jsdelivr.net/gh/rexxzyid/cursanimation@1.5.4/dist/cursanimation.min.js"></script>

Package (GitHub Packages)

Tambahkan registry dan token ke .npmrc, lalu install.

@rexxzyid:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}
npm install @rexxzyid/cursanimation
import CursAnimation from "@rexxzyid/cursanimation";
import "@rexxzyid/cursanimation/css";

CursAnimation.init({ cursor: "ring" });

Package ada di GitHub Packages, jadi instalasi butuh token dengan scope read:packages. Untuk situs statis, CDN lebih sederhana.

Mulai cepat

Inisialisasi kursor sekali, lalu tambahkan rebuild untuk elemen yang ingin dianimasikan saat masuk viewport.

CursAnimation.init({
  cursor: "ring",
  color: "#f3f0e8",
  color2: "#ffd84d",
  size: 32,
  movement: "elastic",
  magnetic: { enabled: true, radius: 90, strength: 0.35 },
  hoverEffects: true
});

CursAnimation.rebuild({
  selector: ".reveal",
  revealClass: "visible",
  typeText: true,
  pen: true
});

Pasangkan dengan CSS berikut supaya elemen tersembunyi sampai proses build selesai.

.reveal {
  opacity: 0;
}

.reveal.visible {
  opacity: 1;
}

Opsi kursor

Semua opsi opsional. Nilai yang tidak valid akan melempar TypeError atau RangeError, bukan diabaikan diam-diam.

OpsiDefaultKeterangan
cursor"default"Tipe kursor. Lihat Tipe kursor.
color / color2#7c5cff / #22d3eeWarna utama dan aksen.
size32Diameter kursor (6–160 px).
movement"smooth"instant, smooth, delayed, elastic.
speed0.25Faktor ikut per frame (0.02–1).
elastic{ stiffness: 0.12, damping: 0.78 }Parameter spring untuk mode elastic.
imageUrl""Wajib jika cursor: "image".
imageSize32Ukuran gambar kursor (8–256 px).
imageHotspot[0, 0]Titik klik di dalam gambar.
hoverEffectstrueAktifkan reaksi hover pada link/tombol/teks.
hoverScale1.8Skala kursor saat hover (0.5–4).
hideNativeCursortrueSembunyikan kursor asli saat mouse aktif.
touch"off"off atau tap untuk feedback sentuh.
respectReducedMotiontrueMatikan efek berat saat pengguna memilih reduced motion.
zIndex2147483000z-index overlay.
selectorslihat contohSelector untuk link, button, text, dan ignore.
selectors: {
  link: "a[href]",
  button: "button, [role=button], summary",
  text: "p, h1, h2, h3, li, blockquote, label",
  ignore: "[data-ca-ignore]"
}

Tipe kursor

default

Kursor lingkaran standar dengan isian.

circle

Lingkaran penuh yang lembut.

dot

Titik kecil, minim distraksi.

ring

Cincin berlubang, cocok untuk tema gelap.

crosshair

Garis bidik seperti aplikasi desain.

minimal

Bentuk paling ringan untuk performa.

image

Gambar custom lewat imageUrl + imageHotspot.

CursAnimation.init({
  cursor: "image",
  imageUrl: "/cursor.png",
  imageSize: 40,
  imageHotspot: [6, 4]
});

Efek

Efek bisa diaktifkan dengan true atau objek untuk mengatur detailnya. trail, particles, clickEffects, magnetic, dan swarm menerima boolean atau objek.

Swarm

Sekumpulan kursor berwarna yang mengorbit, berputar, dan menghindari pointer.

CursAnimation.init({
  cursor: "ring",
  swarm: {
    enabled: true,
    count: 12,
    radius: 150,
    size: 26,
    speed: 1,
    avoid: 52,
    hideCursor: true
  }
});
Opsi swarmDefaultKeterangan
count18Jumlah kursor (2–64).
radius150Jarak orbit (40–500).
size26Ukuran tiap kursor (10–64).
speed1Kecepatan animasi (0.2–3).
avoid52Radius kosong di sekitar pointer.
hideCursortrueSembunyikan kursor tunggal saat swarm aktif.

Trail & partikel

trail: { enabled: true, length: 14, style: "dots", size: 0.6 },
particles: { enabled: true, density: 4, size: 6, lifetime: 800, gravity: 0.04, shape: "dot", max: 120 }

trail.style: dots, gradient, neon. particles.shape: dot, sparkle, mixed.

Magnetik, klik, dan visual

magnetic: { enabled: true, radius: 90, strength: 0.4 },
clickEffects: { enabled: true, ripple: true, particles: true, count: 12 },
glow: false,
neon: false,
motionBlur: false,
dragEffects: true

clickEffects.particles mengatur partikel saat klik; particles utama mengatur partikel jejak.

Reveal

Animasi masuk sederhana berbasis IntersectionObserver. Berbeda dari rebuild: teks tidak dikosongkan, hanya elemen yang ditransformasikan.

CursAnimation.reveal({
  selector: "[data-ca-reveal]",
  once: false,
  threshold: 0.12,
  animation: "fade-up",
  duration: 700,
  stagger: 70,
  distance: 28
});
OpsiDefaultKeterangan
selector"[data-ca-reveal]"Elemen yang dianimasikan.
oncefalseJika false, animasi diputar ulang saat elemen kembali terlihat.
threshold0.12Angka atau array 0–1.
animation"fade-up"fade, fade-up, fade-down, fade-left, fade-right, zoom-in, scale-up, blur-in.
duration700Durasi animasi (ms).
delay0Jeda awal (ms).
stagger70Jeda antar-anak saat induk punya data-ca-stagger.
distance28Jarak gerak (px).
rootMargin"0px"Margin root IntersectionObserver.
rootnullElemen root opsional.
<h2 data-ca-reveal="blur-in">Judul</h2>

<ul data-ca-stagger="80">
  <li data-ca-reveal>Satu</li>
  <li data-ca-reveal data-ca-delay="120">Dua</li>
</ul>

Rebuild on scroll

Efek utama ala Swarm. Saat elemen masuk viewport, library menggambar kotak, mengetik teks per karakter, menelusuri media dengan pen, lalu membersihkan overlay. Jika once: false, elemen dibangun ulang setiap kali kembali terlihat.

1Box

Kursor menggambar outline dan label ukuran.

2Type

Teks diisi karakter demi karakter dengan caret.

3Pen

Garis menelusuri media, lalu media di-reveal.

4Exit

Kursor keluar, overlay dibersihkan, class reveal ditambahkan.

HTML & CSS wajib

<section class="reveal">
  <h2>Judul</h2>
  <p>Deskripsi</p>
</section>
.reveal {
  opacity: 0;
}

.reveal.visible {
  opacity: 1;
}
CursAnimation.rebuild({
  selector: ".reveal",
  revealClass: "visible",
  threshold: 0.14,
  duration: 440,
  agents: 2,
  color: "auto",
  autoDark: "#111111",
  autoLight: "#f3f0e8",
  typeText: true,
  typeSelector: "h1,h2,h3,p,li,blockquote",
  charDelay: 9,
  maxTypeDuration: 980,
  pen: true,
  stagger: 60,
  maxConcurrent: 2
});

Opsi

OpsiDefaultKeterangan
selector"[data-ca-rebuild]"Elemen target.
oncefalseJika true, tidak dibangun ulang.
threshold0.12Batas visibilitas 0–1.
duration520Durasi menggambar kotak (ms).
agents2Jumlah kursor (1–3).
color"#0d99ff"Warna outline/label, atau "auto" untuk kontras otomatis.
autoDark / autoLight#111111 / #ffdc58Warna yang dipakai saat mode auto.
colorsnullPalet kursor; null memakai palet Swarm.
labeltrueTampilkan label ukuran elemen.
labelMinArea7000Luas minimum untuk label (px²).
stagger90Jeda antar elemen (ms).
maxConcurrent2Jumlah build bersamaan.
typeTexttrueKetik teks per karakter.
typeSelectornullBatasi teks yang diketik ke elemen tertentu, mis. "h1,h2,p".
charDelay16Jeda antar karakter (ms).
maxTypeDuration1600Batas total durasi mengetik (ms).
pentrueTelusuri media dengan pen sebelum reveal.
revealClass"ca-built"Class yang ditambahkan agar elemen terlihat.
rootMargin"0px"Margin root IntersectionObserver.
respectReducedMotiontrueLewati animasi saat reduced motion.

Catatan implementasi

  • Replay: dengan once: false, class reveal dilepas saat elemen keluar viewport, lalu build diulang ketika masuk lagi.
  • Teks: teks di dalam typeSelector dikosongkan saat build dimulai. Jangan menaruh elemen interaktif di dalam teks yang diketik.
  • Media: img, svg, video, canvas, picture, dan iframe ikut tertutup sampai fase pen selesai.
  • Konten dinamis: panggil refresh() setelah menambah elemen baru.
  • Performa: gunakan agents: 1, maxConcurrent: 1, typeSelector: "h1,h2", dan duration lebih pendek di mobile.

Live demo

Kartu di bawah memakai rebuild dengan konfigurasi ringan. Scroll keluar lalu masuk lagi untuk melihat replay.

01

Draw

Outline digambar oleh kursor berwarna sebelum konten muncul.

02

Type

Teks diketik karakter demi karakter dengan caret yang berkedip.

03

Pen

Media ditelusuri garis pen, lalu di-reveal dengan transisi.

API

MethodKeterangan
init(options?)Pasang kursor. Memanggil ulang akan mengganti instance sebelumnya.
destroy()Hapus overlay, listener, observer, dan loop.
enable() / disable()Aktifkan/nonaktifkan tanpa menghancurkan instance.
setCursor(type)Shortcut setOptions({ cursor: type }).
setOptions(options)Gabungkan opsi baru ke instance berjalan.
getOptions()Salinan opsi aktif, atau null sebelum init.
isEnabled() / isSupported()Status instance dan dukungan DOM.
reveal(options?)Mulai reveal. Mengembalikan { refresh(), destroy() }.
rebuild(options?)Mulai rebuild. Mengembalikan { refresh(), destroy() }.
refresh()Pindai ulang DOM untuk target hover, magnetik, reveal, dan rebuild.
capabilities()Laporan fitur browser yang terdeteksi.
versionString versi library.

setOptions, setCursor, enable, dan disable melempar error jika init belum dipanggil. Semua method aman dipanggil saat SSR.

Atribut data

AtributDipakai olehFungsi
data-ca-revealRevealMenandai elemen; nilai opsional mengganti animasi.
data-ca-delayRevealJeda khusus elemen (ms).
data-ca-durationRevealDurasi khusus elemen (ms).
data-ca-staggerRevealDipasang di induk untuk jeda antar-anak.
data-ca-hoverKursorPaksa state link, button, text, atau none.
data-ca-ignoreKursorKecualikan elemen dari hover/magnetik.
data-ca-magneticKursorJadikan elemen target magnetik.
data-ca-rebuildRebuildSelector default jika tidak memakai class sendiri.

Performa

Efek kursor berjalan selama pointer bergerak dan bisa membebani perangkat kelas bawah. Rekomendasi:

  • Aktifkan kursor hanya pada perangkat dengan mouse: matchMedia("(pointer: fine)").matches.
  • Kurangi swarm.count (8–12), matikan trail, dan kecilkan clickEffects.count.
  • Di mobile, pakai rebuild ringan: agents: 1, typeSelector: "h1,h2", maxConcurrent: 1.
  • Hindari backdrop-filter, mix-blend-mode, dan layer fixed full-screen di halaman yang berat.
  • Muat script dengan defer agar tidak memblokir render.
  • respectReducedMotion: true otomatis mematikan efek berat bagi pengguna yang memintanya.
const finePointer = matchMedia("(pointer: fine)").matches;

if (finePointer) {
  CursAnimation.init({ cursor: "ring", swarm: { enabled: true, count: 10 } });
}

CursAnimation.rebuild({
  selector: ".reveal",
  agents: 1,
  typeSelector: "h1,h2",
  maxConcurrent: 1
});

Troubleshooting

Kursor tidak muncul

Pastikan CSS sudah dimuat dan init() dipanggil. Cek Console untuk error opsi. Di perangkat sentuh, kursor memang disembunyikan.

Elemen tetap tidak terlihat setelah rebuild

Pastikan revealClass sama dengan CSS, misalnya revealClass: "visible" dan .reveal.visible { opacity: 1 }. Tanpa IntersectionObserver, elemen langsung ditampilkan.

Rebuild tidak mengulang

Gunakan once: false (default). Elemen harus benar-benar keluar viewport agar class reveal dilepas.

Garis overlay salah posisi saat scroll

Gunakan versi 1.5.3 ke atas — overlay sudah menempel ke dokumen, bukan viewport.

Gagal install dari GitHub Packages

Tambahkan .npmrc dan token dengan scope read:packages. Alternatif termudah: pakai CDN.

Kursor ganda

Pastikan hanya satu instance CursAnimation yang aktif. Panggil destroy() sebelum init ulang, atau gunakan setOptions().

Browser & lisensi

Menggunakan feature detection, bukan sniffing. Pointer Events dipakai bila tersedia; tanpa matchMedia efek tetap aktif; tanpa IntersectionObserver elemen langsung tampil. Overlay selalu pointer-events: none dan animasi berhenti saat tab tidak aktif.

Lisensi MIT. Dibuat oleh RexxHayanasi. Terinspirasi dari Swarm Rebuild, tanpa kode atau aset dari proyek tersebut.