https://github.com/code-parth/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/code-parth/smooth-cursor
animation cursor cursor-customization cursor-effects custom-cursor framer-motion interactive motion-design mouse-movement mouse-tracking performance-optimized physics-based react react-component rotation-animation smooth-cursor spring-animation typescript ui-component velocity-tracking
Last synced: 5 months ago
JSON representation
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.
- Host: GitHub
- URL: https://github.com/code-parth/smooth-cursor
- Owner: Code-Parth
- License: mit
- Created: 2025-02-12T11:40:26.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-02-12T14:21:42.000Z (11 months ago)
- Last Synced: 2025-08-11T21:49:46.305Z (5 months ago)
- Topics: animation, cursor, cursor-customization, cursor-effects, custom-cursor, framer-motion, interactive, motion-design, mouse-movement, mouse-tracking, performance-optimized, physics-based, react, react-component, rotation-animation, smooth-cursor, spring-animation, typescript, ui-component, velocity-tracking
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/smooth-cursor
- Size: 31.3 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
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](https://figbruary.apexia.club)** - See the smooth cursor in action!
## 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
```bash
npm install smooth-cursor
# or
yarn add smooth-cursor
# or
pnpm add smooth-cursor
```
## Usage
### Next.js Integration
#### App Router (Next.js 13+)
```tsx
// app/layout.tsx
'use client';
import { SmoothCursor } from 'smooth-cursor';
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
{children}
);
}
```
#### Pages Router
```tsx
// pages/_app.tsx
import type { AppProps } from 'next/app';
import { SmoothCursor } from 'smooth-cursor';
export default function App({ Component, pageProps }: AppProps) {
return (
<>
>
);
}
```
### Basic Usage
```jsx
import { SmoothCursor } from 'smooth-cursor';
function App() {
return (
{/* Your app content */}
);
}
```
### Custom Cursor
```jsx
import { SmoothCursor } from 'smooth-cursor';
const CustomCursor = () => (
);
function App() {
return (
} />
{/* Your app content */}
);
}
```
## Props
| Prop | Type | Default | Description |
|------|------|---------|-------------|
| cursor | JSX.Element | `` | Custom cursor component to replace the default cursor |
| springConfig | SpringConfig | See below | Configuration object for the spring animation behavior |
### SpringConfig Type
```typescript
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
```typescript
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
```tsx
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 (
{/* Your app content */}
);
}
```
## Animation Configuration
The cursor uses Framer Motion's spring animation with the following default configuration:
```typescript
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:
```bash
# 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.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Credits
Created by [Code-Parth](https://github.com/Code-Parth)
## Support
If you have any questions or need help integrating the component, please [open an issue](https://github.com/Code-Parth/smooth-cursor/issues).