CursorLab 🎯

Interactive cursor trails with real-time parameter controls

A powerful, lightweight, and modular JavaScript library for creating custom mouse cursors and trail effects in web applications. Transform your user experience with smooth-following trails and customizable cursor styles.

✨ Features

🎨 Modular API: Each property has its own method for maximum flexibility
🖱️ Multiple Trail Types: Circle, Square, Triangle, Star, Dot (filled and hollow variants)
🎯 Custom Cursors: Built-in cursors, crosshair generator, and image cursor support
⚙️ Full Customization: Size, thickness, color, delay, and custom CSS styling
🌟 Overlapping Trails: Create multiple trails that run simultaneously
🔗 Method Chaining: Combine multiple effects effortlessly
🚀 Performance Optimized: Smooth 60fps animations with requestAnimationFrame
💻 CLI Help: Built-in command-line help with cursorlab help
📱 Universal Compatibility: Works in browsers and Node.js environments
💼 Zero Dependencies: Lightweight and self-contained

🚀 Quick Start

Installation

npm install cursorlab

# Try the interactive demo!
cursorlab demo

Basic Usage

<!-- Include in HTML -->
<script src="node_modules/cursorlab/browser.js"></script>

<script>
// Set a circle trail with custom properties
CursorLab.setCursorTrail('circle')
         .setColor('#ff0000')
         .setSize(20)
         .setThickness(3)
         .trailDelay(0.1)
         .startTrail();
</script>

// Node.js / ES6 Module
const CursorLab = require('cursorlab');

// Create instance for advanced control
const cursor = new CursorLab();
cursor.setCursorTrail('star')
      .setColor('#00ff00')
      .setSize(25)
      .startTrail();

📚 Modular API

CursorLab uses a modular approach where each property has its own method. This allows for maximum flexibility and clear, readable code.

Core Methods

`setCursorTrail(type)`

Set the trail shape that follows your cursor.

Available Types:

'circle' - Hollow circle
'circle-filled' - Filled circle
'square' - Hollow square
'square-filled' - Filled square
'triangle' - Triangle shape
'star' - Star shape
'dot' - Small filled circle

CursorLab.setCursorTrail('circle');
CursorLab.setCursorTrail('star');

`setSize(widthOrRadius, height)`

Control the trail dimensions.

// Single parameter - sets radius for circles/dots, or size for squares/stars
CursorLab.setSize(20);

// Two parameters - sets width and height independently
CursorLab.setSize(30, 20); // 30px wide, 20px tall

`setThickness(thickness)`

Set border thickness for hollow shapes.

CursorLab.setThickness(1); // Thin border
CursorLab.setThickness(5); // Thick border

`setColor(color)`

Set the trail color using any CSS color format.

CursorLab.setColor('#ff0000');        // Hex
CursorLab.setColor('red');            // Named color
CursorLab.setColor('rgb(255,0,0)');   // RGB
CursorLab.setColor('hsl(0,100%,50%)'); // HSL

`trailDelay(delay)`

Control how quickly the trail follows the cursor (0.01 = fast, 0.3 = slow).

CursorLab.trailDelay(0.05); // Fast following
CursorLab.trailDelay(0.1);  // Normal speed
CursorLab.trailDelay(0.3);  // Slow following

`startTrail()`

Begin the trail animation. Call this after setting up your trail properties.

CursorLab.setCursorTrail('circle').setColor('blue').startTrail();

Cursor Methods

`setCustomCursor(cursorType, param1, param2)`

Change the actual cursor appearance.

Built-in Cursors:

CursorLab.setCustomCursor('grab');
CursorLab.setCustomCursor('copy');
CursorLab.setCustomCursor('none'); // Hide cursor

Custom Crosshair:

// setCustomCursor('crosshair', thickness, length)
CursorLab.setCustomCursor('crosshair', 2, 15);
CursorLab.setCustomCursor('crosshair', 4, 25); // Thicker, longer

Image Cursors:

// Use any image as cursor
CursorLab.setCustomCursor('url(path/to/cursor.png), auto');
CursorLab.setCustomCursor('url(data:image/png;base64,iVBOR...), auto');

`setCustomStyle(cssStyles)`

Apply advanced CSS styling.

Object Format:

CursorLab.setCustomStyle({
    cursor: 'none',
    'pointer-events': 'auto'
});

CSS String Format:

CursorLab.setCustomStyle(`
    .cursorlab-trail {
        filter: blur(2px) !important;
        opacity: 0.7 !important;
        animation: pulse 1s infinite !important;
    }
    @keyframes pulse {
        0%, 100% { transform: translate(-50%, -50%) scale(1); }
        50% { transform: translate(-50%, -50%) scale(1.2); }
    }
`);

🔗 Method Chaining

All methods return this, enabling powerful method chaining:

// Basic chaining
CursorLab.setCursorTrail('circle')
         .setColor('#ff0000')
         .setSize(20)
         .startTrail();

// Complex combination
CursorLab.setCursorTrail('star')
         .setColor('#9b59b6')
         .setSize(25)
         .setThickness(3)
         .trailDelay(0.08)
         .setCustomCursor('grab')
         .setCustomStyle({cursor: 'none'})
         .startTrail();

// Multiple effects
const cursor = new CursorLab();
cursor.setCursorTrail('triangle')
      .setColor('#e74c3c')
      .setSize(30, 25)      // width, height
      .trailDelay(0.12)
      .setCustomCursor('crosshair', 3, 20)
      .startTrail();

// Create new trail (replaces any existing trail)
CursorLab.setCursorTrail('circle').setColor('#ff0000').setSize(25).startTrail();

🎮 Control Methods

// Remove all trails (keeps cursor changes)
CursorLab.setDefault();

// Reset cursor to original
CursorLab.setNormalCursor();

// Remove everything and clean up
CursorLab.destroy();

// Check if any trail is active
if (CursorLab.isActive()) {
    console.log('Trails are running');
}

🎨 Complete Examples

Rainbow Star with Custom Cursor

CursorLab.setCursorTrail('star')
         .setColor('#ff00ff')
         .setSize(30)
         .trailDelay(0.06)
         .setCustomCursor('crosshair', 2, 18)
         .setCustomStyle(`
             .cursorlab-trail {
                 animation: rainbow 2s infinite !important;
             }
             @keyframes rainbow {
                 0% { filter: hue-rotate(0deg); }
                 100% { filter: hue-rotate(360deg); }
             }
         `)
         .startTrail();

Spinning Square Trail

CursorLab.setCursorTrail('square')
         .setColor('#f39c12')
         .setSize(22)
         .setThickness(4)
         .trailDelay(0.15)
         .setCustomStyle(`
             .cursorlab-trail {
                 animation: spin 1s linear infinite !important;
             }
             @keyframes spin {
                 from { transform: translate(-50%, -50%) rotate(0deg); }
                 to { transform: translate(-50%, -50%) rotate(360deg); }
             }
         `)
         .startTrail();

Variable Sizes and Speeds

// Small fast dot
CursorLab.setCursorTrail('dot')
         .setSize(8)
         .setColor('#1abc9c')
         .trailDelay(0.03)
         .startTrail();

// Large slow circle  
CursorLab.setCursorTrail('circle')
         .setSize(40)
         .setThickness(2)
         .setColor('#e74c3c')
         .trailDelay(0.25)
         .startTrail();

🏗️ Instance vs Static Usage

Static Methods (Global Instance)

// Uses a global instance automatically
CursorLab.setCursorTrail('circle').setColor('red').startTrail();
CursorLab.setDefault(); // Reset the trail

Instance Methods (Independent Control)

// Create separate instances for independent control
const cursor1 = new CursorLab();
const cursor2 = new CursorLab();

cursor1.setCursorTrail('circle').setColor('blue').startTrail();
cursor2.setCursorTrail('star').setColor('red').startTrail();

📋 API Reference

Trail Configuration

Method	Parameters	Description
`setCursorTrail(type)`	`type: string`	Set trail shape
`setSize(size)`	`size: number`	Set uniform size
`setSize(width, height)`	`width: number, height: number`	Set dimensions
`setThickness(thickness)`	`thickness: number`	Set border thickness
`setColor(color)`	`color: string`	Set trail color
`trailDelay(delay)`	`delay: number`	Set follow speed
`startTrail()`	-	Begin trail animation

Cursor Control

Method	Parameters	Description
`setCustomCursor(type)`	`type: string`	Set CSS cursor
`setCustomCursor('crosshair', thickness, length)`	`thickness: number, length: number`	Custom crosshair
`setCustomCursor(imageUrl)`	`imageUrl: string`	Image cursor
`setCustomStyle(styles)`	`styles: object\|string`	Custom CSS

Control Methods

Method	Parameters	Description
`setDefault()`	-	Remove trail
`setNormalCursor()`	-	Reset cursor
`destroy()`	-	Clean up everything
`isActive()`	-	Check if active

💻 CLI Help

CursorLab includes a built-in command-line interface for quick reference:

# After installation
npm install cursorlab

# Get comprehensive help
cursorlab help

# Open interactive demo in browser
cursorlab demo

# Check version
cursorlab version

The CLI provides:

Complete API documentation
Method chaining examples
Browser and Node.js examples
Performance tips and best practices
Interactive demo with live controls - cursorlab demo

Perfect for quick reference while coding!

🔧 Customization Tips

Performance Optimization

Use trailDelay(0.1) or higher for better performance on slower devices
Avoid very complex CSS animations in setCustomStyle()
Call destroy() when removing the trail to prevent memory leaks

Visual Effects

Combine trails with CSS filters: blur(), drop-shadow(), brightness()
Use CSS animations for rotating, pulsing, or color-changing effects
Create visual depth with different colors and delays

Browser Compatibility

Image cursors work best with PNG files under 32x32 pixels
Use data URLs for embedded cursor images
Test crosshair cursors across different browsers for consistency

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT License - see the LICENSE file for details.

Name		Name	Last commit message	Last commit date
Latest commit History 7 Commits
src		src
LICENSE		LICENSE
README.md		README.md
browser.js		browser.js
cli.js		cli.js
cursorlab_sample.gif		cursorlab_sample.gif
demo.html		demo.html
index.js		index.js
package.json		package.json

License

RonitSachdev/CursorLab

Folders and files

Latest commit

History

Repository files navigation

CursorLab 🎯

✨ Features

🚀 Quick Start

Installation

Basic Usage

📚 Modular API

Core Methods

setCursorTrail(type)

setSize(widthOrRadius, height)

setThickness(thickness)

setColor(color)

trailDelay(delay)

startTrail()

Cursor Methods

setCustomCursor(cursorType, param1, param2)

setCustomStyle(cssStyles)