cursor-blob

cursor-blob

^{Lightweight library for animated, interactive cursors using GSAP}

^{1.2kB gzipped}

Demo

➤ Install

$ yarn add gsap
$ yarn add cursor-blob

➤ Import

import gsap from 'gsap';
import CursorBlob from 'cursor-blob';

➤ Usage

<div class="cursor">
  <div class="cursor__rim"></div>
  <div class="cursor__dot"></div>
</div>

CursorBlob.registerGSAP(gsap);

const cursorEl = document.querySelector('.cursor');
const cursorRimEl = document.querySelector('.cursor__rim');
const cursorDotEl = document.querySelector('.cursor__dot');

const cursorBlob = new CursorBlob({
  cursorEl,
  cursorRimEl,
  cursorDotEl,
  duration: 0.8,
  ease: 'expo.out',
});

The CursorBlob plugin supports dynamically changing the cursor's appearance using the data-cursor-style attribute. You can add this data attribute to any HTML element to define custom behavior and cursor style on hover.

How it works

Each element with the attribute data-cursor-style="your-style" will switch the cursor’s class to cursor--your-style. For example:

<div data-cursor-style="blend">...</div>

This will add the class .cursor--blend to the cursor element. You can then define the necessary styles in CSS using this class. Examples.

➤ Options

Option	Type	Default	Description
cursorEl	HTMLElement	–	Main cursor wrapper element.
cursorRimEl	HTMLElement	–	Outer ring of the cursor that stretches and rotates based on velocity.
cursorDotEl	HTMLElement	–	Inner dot of the cursor that lags slightly behind.
duration	number	–	Duration of the GSAP animation when the cursor moves.
ease	string	'expo.out'	Easing function used by GSAP for smooth motion. See gsap easing.

➤ API

Method	Description
destroy()	Removes all event listeners and cancels the animation loop.

➤ License cursor-blob is released under MIT license.