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!
- 🎯 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';exportdefaultfunctionRootLayout({
children,}: {children: React.ReactNode;}){return(<htmllang="en"><body><SmoothCursor/>{children}</body></html>);}// pages/_app.tsximporttype{AppProps}from'next/app';import{SmoothCursor}from'smooth-cursor';exportdefaultfunctionApp({ Component, pageProps }: AppProps){return(<><SmoothCursor/><Component{...pageProps}/></>);}import{SmoothCursor}from'smooth-cursor';functionApp(){return(<div><SmoothCursor/>{/* Your app content */}</div>);}import{SmoothCursor}from'smooth-cursor';constCustomCursor=()=>(<divclassName="w-8 h-8 bg-blue-500 rounded-full"/>);functionApp(){return(<div><SmoothCursorcursor={<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 |
interfaceSpringConfig{damping: number;// Controls how quickly the animation settlesstiffness: number;// Controls the spring stiffnessmass: number;// Controls the virtual mass of the animated objectrestDelta: number;// Controls the threshold at which animation is considered complete}constdefaultSpringConfig={damping: 45,// Default damping valuestiffness: 400,// Default stiffness valuemass: 1,// Default mass valuerestDelta: 0.001// Default rest delta value}functionApp(){constcustomSpringConfig={damping: 60,// Higher damping for less oscillationstiffness: 500,// Higher stiffness for faster movementmass: 1.2,// Slightly more mass for momentumrestDelta: 0.0005// Smaller rest delta for more precise settling};return(<div><SmoothCursorspringConfig={customSpringConfig}/>{/* Your app content */}</div>);}The cursor uses Framer Motion's spring animation with the following default configuration:
constspringConfig={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.