codxell-cursor

A smooth, fluid, and magnetic custom cursor component for React and Next.js applications.

Features

• 🖱️ Fluid Movement: Smooth cursor following with physics-based interpolation.
• 🧲 Magnetic Effect: Automatically snaps to interactive elements (buttons, links, etc.).
• 🤏 Dynamic Stretching: squashes and stretches based on movement speed and direction.
• 🎨 Customizable: Full control over size, colors, smoothing, and behavior.
• ✨ Magic Mode: Optional inverted color mode for better visibility on dark/light backgrounds.

Demo

🎥 Watch Video Demo - See the cursor in action!

💻 Live Demo Repository - Check out the source code and examples.

Installation

npm install codxell-cursor
# or
yarn add codxell-cursor
# or
pnpm add codxell-cursor

Usage

Import the Cursor component and place it in your main layout or page.

import { Cursor } from 'codxell-cursor';

export default function App() {
  return (
    <main>
      <Cursor 
        size={20}
        smoothing={0.2}
        bg="magic" // Optional: Inverted color mode
      />
      
      {/* Your app content */}
      <button data-hover>Hover Me</button>
    </main>
  );
}

Interactive Elements

Add the data-hover attribute to any element you want the cursor to magnetically snap to.

<button data-hover>I'm Magnetic!</button>
<a href="#" data-hover>Me too!</a>

You can also use data-cursor="pointer" to explicitly set the system cursor style when hovering.

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | size | number | 15 | The size of the cursor in pixels. | | smoothing | number | 0.18 | The smoothing factor for cursor movement (0-1). Lower is smoother/slower. | | stretchSensitivity | number | 0.5 | How much the cursor stretches when moving. | | maxStretch | number | 1 | Maximum stretch factor. | | verticalSqueeze | number | 0.6 | How much the cursor squeezes vertically when stretching. | | magneticSmoothing | number | 0.25 | Smoothing factor when snapping to elements. | | magneticBorderRadius | string | "1rem" | Border radius applied to the cursor when snapping to an element. | | hoverSelector | string | "[data-hover], [data-cursor]" | CSS selector for elements that trigger the magnetic effect. | | bg | string | undefined | Background color. Set to "magic" for inverted mix-blend-mode effect. | | zIndex | number | 99999 | Z-index of the cursor. | | className | string | undefined | Custom CSS class for the cursor container. | | style | CSSProperties | undefined | Custom inline styles. |

License

MIT