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.
Screen.Recording.2025εΉ΄02ζ12ζ₯.at.18.14.04.mov
π― Live Preview - See the smooth cursor in action!
GitHub package.json version NPM Version License
- π― 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 rollup
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
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.