smooth-cursor

v0.1.2

Published

10 months ago

A customizable, physics-based smooth cursor animation component for React applications with spring animations, velocity tracking, and rotation effects

Downloads

Smooth Cursor

A highly customizable, physics-based smooth cursor animation component for React applications. Features spring animations, velocity tracking, and rotation effects for creating engaging cursor experiences.

https://github.com/user-attachments/assets/2b56dea7-9e98-4563-9b61-ab668b08d2e5

🎯 Live Preview - See the smooth cursor in action!

GitHub package.json version NPM Version License

Features

🎯 Smooth physics-based cursor animations
🔄 Rotation effects based on movement direction
⚡ Performance optimized with RAF
🎨 Fully customizable cursor design
📦 Lightweight and easy to implement
💪 Written in TypeScript
🔌 Powered by Framer Motion

Installation

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

Usage

Next.js Integration

App Router (Next.js 13+)

// app/layout.tsx
'use client';

import { SmoothCursor } from 'smooth-cursor';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <SmoothCursor />
        {children}
      </body>
    </html>
  );
}

Pages Router

// pages/_app.tsx
import type { AppProps } from 'next/app';
import { SmoothCursor } from 'smooth-cursor';

export default function App({ Component, pageProps }: AppProps) {
  return (
    <>
      <SmoothCursor />
      <Component {...pageProps} />
    </>
  );
}

Basic Usage

import { SmoothCursor } from 'smooth-cursor';

function App() {
  return (
    <div>
      <SmoothCursor />
      {/* Your app content */}
    </div>
  );
}

Custom Cursor

import { SmoothCursor } from 'smooth-cursor';

const CustomCursor = () => (
  <div className="w-8 h-8 bg-blue-500 rounded-full" />
);

function App() {
  return (
    <div>
      <SmoothCursor cursor={<CustomCursor />} />
      {/* Your app content */}
    </div>
  );
}

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | cursor | JSX.Element | <DefaultCursorSVG /> | Custom cursor component to replace the default cursor | | springConfig | SpringConfig | See below | Configuration object for the spring animation behavior |

SpringConfig Type

interface SpringConfig {
    damping: number;    // Controls how quickly the animation settles
    stiffness: number;  // Controls the spring stiffness
    mass: number;       // Controls the virtual mass of the animated object
    restDelta: number;  // Controls the threshold at which animation is considered complete
}

Default Spring Configuration

const defaultSpringConfig = {
    damping: 45,      // Default damping value
    stiffness: 400,   // Default stiffness value
    mass: 1,          // Default mass value
    restDelta: 0.001  // Default rest delta value
}

Usage with Custom Spring Configuration

function App() {
  const customSpringConfig = {
    damping: 60,      // Higher damping for less oscillation
    stiffness: 500,   // Higher stiffness for faster movement
    mass: 1.2,        // Slightly more mass for momentum
    restDelta: 0.0005 // Smaller rest delta for more precise settling
  };

  return (
    <div>
      <SmoothCursor springConfig={customSpringConfig} />
      {/* Your app content */}
    </div>
  );
}

Animation Configuration

The cursor uses Framer Motion's spring animation with the following default configuration:

const springConfig = {
  damping: 45,
  stiffness: 400,
  mass: 1,
  restDelta: 0.001
};

Browser Support

The component is compatible with all modern browsers that support:

requestAnimationFrame
CSS transforms
Pointer events

Performance Considerations

The component is optimized for performance by:

Using requestAnimationFrame for smooth animations
Implementing throttling for mouse movement events
Using hardware-accelerated transforms
Optimizing re-renders with React's lifecycle methods

Development

To run the development environment:

# Install dependencies
npm install

# Build the package
npm run rollup

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Credits

Created by Code-Parth

Support

If you have any questions or need help integrating the component, please open an issue.