Package Exports

smooth-cursor
smooth-cursor/dist/cjs/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (smooth-cursor) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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.