default
Kursor lingkaran standar dengan isian.
Dokumentasi
Library custom cursor dan animasi rebuild on scroll tanpa dependency. Kursor, swarm, trail, partikel, magnetik, klik, reveal, dan efek membangun elemen seperti di Swarm.
Ada dua cara: CDN untuk HTML statis, atau package untuk project dengan bundler. Stylesheet wajib dimuat — tanpa CSS, overlay tidak akan tampil.
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>
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.
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;
}
Semua opsi opsional. Nilai yang tidak valid akan melempar TypeError atau RangeError, bukan diabaikan diam-diam.
| Opsi | Default | Keterangan |
|---|---|---|
cursor | "default" | Tipe kursor. Lihat Tipe kursor. |
color / color2 | #7c5cff / #22d3ee | Warna utama dan aksen. |
size | 32 | Diameter kursor (6–160 px). |
movement | "smooth" | instant, smooth, delayed, elastic. |
speed | 0.25 | Faktor ikut per frame (0.02–1). |
elastic | { stiffness: 0.12, damping: 0.78 } | Parameter spring untuk mode elastic. |
imageUrl | "" | Wajib jika cursor: "image". |
imageSize | 32 | Ukuran gambar kursor (8–256 px). |
imageHotspot | [0, 0] | Titik klik di dalam gambar. |
hoverEffects | true | Aktifkan reaksi hover pada link/tombol/teks. |
hoverScale | 1.8 | Skala kursor saat hover (0.5–4). |
hideNativeCursor | true | Sembunyikan kursor asli saat mouse aktif. |
touch | "off" | off atau tap untuk feedback sentuh. |
respectReducedMotion | true | Matikan efek berat saat pengguna memilih reduced motion. |
zIndex | 2147483000 | z-index overlay. |
selectors | lihat contoh | Selector 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]"
}
Kursor lingkaran standar dengan isian.
Lingkaran penuh yang lembut.
Titik kecil, minim distraksi.
Cincin berlubang, cocok untuk tema gelap.
Garis bidik seperti aplikasi desain.
Bentuk paling ringan untuk performa.
Gambar custom lewat imageUrl + imageHotspot.
CursAnimation.init({
cursor: "image",
imageUrl: "/cursor.png",
imageSize: 40,
imageHotspot: [6, 4]
});
Efek bisa diaktifkan dengan true atau objek untuk mengatur detailnya. trail, particles, clickEffects, magnetic, dan swarm menerima boolean atau objek.
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 swarm | Default | Keterangan |
|---|---|---|
count | 18 | Jumlah kursor (2–64). |
radius | 150 | Jarak orbit (40–500). |
size | 26 | Ukuran tiap kursor (10–64). |
speed | 1 | Kecepatan animasi (0.2–3). |
avoid | 52 | Radius kosong di sekitar pointer. |
hideCursor | true | Sembunyikan kursor tunggal saat swarm aktif. |
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.
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.
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
});
| Opsi | Default | Keterangan |
|---|---|---|
selector | "[data-ca-reveal]" | Elemen yang dianimasikan. |
once | false | Jika false, animasi diputar ulang saat elemen kembali terlihat. |
threshold | 0.12 | Angka atau array 0–1. |
animation | "fade-up" | fade, fade-up, fade-down, fade-left, fade-right, zoom-in, scale-up, blur-in. |
duration | 700 | Durasi animasi (ms). |
delay | 0 | Jeda awal (ms). |
stagger | 70 | Jeda antar-anak saat induk punya data-ca-stagger. |
distance | 28 | Jarak gerak (px). |
rootMargin | "0px" | Margin root IntersectionObserver. |
root | null | Elemen 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>
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.
Kursor menggambar outline dan label ukuran.
Teks diisi karakter demi karakter dengan caret.
Garis menelusuri media, lalu media di-reveal.
Kursor keluar, overlay dibersihkan, class reveal ditambahkan.
<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 | Default | Keterangan |
|---|---|---|
selector | "[data-ca-rebuild]" | Elemen target. |
once | false | Jika true, tidak dibangun ulang. |
threshold | 0.12 | Batas visibilitas 0–1. |
duration | 520 | Durasi menggambar kotak (ms). |
agents | 2 | Jumlah kursor (1–3). |
color | "#0d99ff" | Warna outline/label, atau "auto" untuk kontras otomatis. |
autoDark / autoLight | #111111 / #ffdc58 | Warna yang dipakai saat mode auto. |
colors | null | Palet kursor; null memakai palet Swarm. |
label | true | Tampilkan label ukuran elemen. |
labelMinArea | 7000 | Luas minimum untuk label (px²). |
stagger | 90 | Jeda antar elemen (ms). |
maxConcurrent | 2 | Jumlah build bersamaan. |
typeText | true | Ketik teks per karakter. |
typeSelector | null | Batasi teks yang diketik ke elemen tertentu, mis. "h1,h2,p". |
charDelay | 16 | Jeda antar karakter (ms). |
maxTypeDuration | 1600 | Batas total durasi mengetik (ms). |
pen | true | Telusuri media dengan pen sebelum reveal. |
revealClass | "ca-built" | Class yang ditambahkan agar elemen terlihat. |
rootMargin | "0px" | Margin root IntersectionObserver. |
respectReducedMotion | true | Lewati animasi saat reduced motion. |
once: false, class reveal dilepas saat elemen keluar viewport, lalu build diulang ketika masuk lagi.typeSelector dikosongkan saat build dimulai. Jangan menaruh elemen interaktif di dalam teks yang diketik.img, svg, video, canvas, picture, dan iframe ikut tertutup sampai fase pen selesai.refresh() setelah menambah elemen baru.agents: 1, maxConcurrent: 1, typeSelector: "h1,h2", dan duration lebih pendek di mobile.Kartu di bawah memakai rebuild dengan konfigurasi ringan. Scroll keluar lalu masuk lagi untuk melihat replay.
Outline digambar oleh kursor berwarna sebelum konten muncul.
Teks diketik karakter demi karakter dengan caret yang berkedip.
Media ditelusuri garis pen, lalu di-reveal dengan transisi.
| Method | Keterangan |
|---|---|
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. |
version | String versi library. |
setOptions, setCursor, enable, dan disable melempar error jika init belum dipanggil. Semua method aman dipanggil saat SSR.
| Atribut | Dipakai oleh | Fungsi |
|---|---|---|
data-ca-reveal | Reveal | Menandai elemen; nilai opsional mengganti animasi. |
data-ca-delay | Reveal | Jeda khusus elemen (ms). |
data-ca-duration | Reveal | Durasi khusus elemen (ms). |
data-ca-stagger | Reveal | Dipasang di induk untuk jeda antar-anak. |
data-ca-hover | Kursor | Paksa state link, button, text, atau none. |
data-ca-ignore | Kursor | Kecualikan elemen dari hover/magnetik. |
data-ca-magnetic | Kursor | Jadikan elemen target magnetik. |
data-ca-rebuild | Rebuild | Selector default jika tidak memakai class sendiri. |
Efek kursor berjalan selama pointer bergerak dan bisa membebani perangkat kelas bawah. Rekomendasi:
matchMedia("(pointer: fine)").matches.swarm.count (8–12), matikan trail, dan kecilkan clickEffects.count.agents: 1, typeSelector: "h1,h2", maxConcurrent: 1.backdrop-filter, mix-blend-mode, dan layer fixed full-screen di halaman yang berat.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
});
Pastikan CSS sudah dimuat dan init() dipanggil. Cek Console untuk error opsi. Di perangkat sentuh, kursor memang disembunyikan.
Pastikan revealClass sama dengan CSS, misalnya revealClass: "visible" dan .reveal.visible { opacity: 1 }. Tanpa IntersectionObserver, elemen langsung ditampilkan.
Gunakan once: false (default). Elemen harus benar-benar keluar viewport agar class reveal dilepas.
Gunakan versi 1.5.3 ke atas — overlay sudah menempel ke dokumen, bukan viewport.
Tambahkan .npmrc dan token dengan scope read:packages. Alternatif termudah: pakai CDN.
Pastikan hanya satu instance CursAnimation yang aktif. Panggil destroy() sebelum init ulang, atau gunakan setOptions().
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.