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!
- 🎯 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
npm install smooth-cursor
# or
yarn add smooth-cursor
# or
pnpm add smooth-cursor// 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/_app.tsx
import type { AppProps } from 'next/app';
import { SmoothCursor } from 'smooth-cursor';
export default function App({ Component, pageProps }: AppProps) {
return (
<>
<SmoothCursor />
<Component {...pageProps} />
</>
);
}import { SmoothCursor } from 'smooth-cursor';
function App() {
return (
<div>
<SmoothCursor />
{/* Your app content */}
</div>
);
}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>
);
}| 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 |
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
}const defaultSpringConfig = {
damping: 45, // Default damping value
stiffness: 400, // Default stiffness value
mass: 1, // Default mass value
restDelta: 0.001 // Default rest delta value
}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>
);
}The cursor uses Framer Motion's spring animation with the following default configuration:
const springConfig = {
damping: 45,
stiffness: 400,
mass: 1,
restDelta: 0.001
};The component is compatible with all modern browsers that support:
requestAnimationFrame- CSS transforms
- Pointer events
The component is optimized for performance by:
- Using
requestAnimationFramefor smooth animations - Implementing throttling for mouse movement events
- Using hardware-accelerated transforms
- Optimizing re-renders with React's lifecycle methods
To run the development environment:
# Install dependencies
npm install
# Build the package
npm run rollupContributions 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
This project is licensed under the MIT License - see the LICENSE file for details.
Created by Code-Parth
If you have any questions or need help integrating the component, please open an issue.