Skip to content

Commit ef0ae71

Browse files
areknowareknow
committed
readme
1 parent 83707d9 commit ef0ae71

File tree

1 file changed

+119
-78
lines changed

1 file changed

+119
-78
lines changed

‎README.md‎

Lines changed: 119 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -1,104 +1,166 @@
1-
# React Gradient Hover
1+
# React Use Cursor Follow
22

3-
A high-performance React component that creates an elegant, interactive gradient effect that follows cursor movement. Perfect for creating engaging hover states and modern UI elements.
3+
A lightweight React hook that creates a smooth, customizable animated cursor element that follows your mouse movement. Perfect for creating modern, interactive user experiences with custom cursor effects.
44

5-
[![npm version](https://img.shields.io/npm/v/react-gradient-hover.svg)](https://www.npmjs.com/package/react-gradient-hover)
5+
[![npm version](https://img.shields.io/npm/v/react-use-cursor-follow.svg)](https://www.npmjs.com/package/react-use-cursor-follow)
66
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
7-
[![GitHub Pages](https://img.shields.io/badge/GitHub%20Pages-Documentation-blue)](https://areknow.github.io/react-gradient-hover/)
87

98
## Overview
109

11-
React Gradient Hover enhances your UI with smooth, performant gradient animations that respond to user interaction. The component creates a dynamic spotlight effect that follows the cursor, providing a modern and engaging user experience.
10+
React Use Cursor Follow provides a performant way to create custom cursor effects that smoothly follow mouse movement. The hook creates a floating element that trails behind your cursor with customizable easing, size, color, and behavior options.
1211

1312
### Key Features
1413

15-
- 🎨 Fluid gradient animations using requestAnimationFrame
16-
- 🌈 Support for multiple gradient colors (minimum of 2)
17-
- ⚡ Optimized performance with debounced event handling
18-
- 🎯 Customizable animation speed and transition duration
19-
- 📱 Responsive design with automatic resizing
14+
- 🎯 Smooth cursor following with customizable easing
15+
- 🎨 Fully customizable appearance (color, size, shape)
16+
- ⚡ Optimized performance with configurable update intervals
17+
- 🌅 Smart fade effects near viewport edges
18+
- 👁️ Optional default cursor hiding
2019
- 🔧 TypeScript support with comprehensive type definitions
21-
- 🎪 Smooth return-to-center animation
20+
- 📱 Responsive and works across all screen sizes
21+
- 🎪 Automatic cleanup and memory management
2222

2323
## Installation
2424

2525
```bash
26-
npm install react-gradient-hover
26+
npm install react-use-cursor-follow
2727
```
2828

2929
or
3030

3131
```bash
32-
yarn add react-gradient-hover
32+
yarn add react-use-cursor-follow
3333
```
3434

3535
## Quick Start
3636

3737
```tsx
38-
import { GradientHover } from "react-gradient-hover";
38+
import { useCursorFollow } from "react-use-cursor-follow";
3939

4040
function App() {
41+
useCursorFollow({ color: "red" });
42+
4143
return (
42-
<GradientHover>
43-
<div style={{ padding: "2rem" }}>
44-
<h2>Interactive Gradient</h2>
45-
<p>Hover to see the effect in action</p>
46-
</div>
47-
</GradientHover>
44+
<div>
45+
<h1>Move your mouse around!</h1>
46+
<p>You'll see a custom red cursor following your mouse.</p>
47+
</div>
4848
);
4949
}
5050
```
5151

52-
## Component API
52+
## Hook API
5353

54-
### Props
54+
### Options
5555

56-
| Prop | Type | Default | Description |
57-
| -------------------------- | --------------- | ------------------------ | ------------------------------------------- |
58-
| `colors` | `string[]` | `['#EB2DD2', '#5AB5EE']` | Array of gradient colors (minimum 2) |
59-
| `children` | `ReactNode` | Required | Content to wrap with the gradient effect |
60-
| `className` | `string` | `''` | Additional CSS class names |
61-
| `style` | `CSSProperties` | `{}` | Additional inline styles |
62-
| `onClick` | `() => void` | - | Optional click handler |
63-
| `animationSpeed` | `number` | `5` | Animation speed (1-10, where 10 is fastest) |
64-
| `transitionDuration` | `number` | `1` | Transition duration in seconds |
65-
| `shouldAlwaysShowGradient` | `boolean` | `true` | Whether to show gradient before hover |
56+
| Option | Type | Default | Description |
57+
| ---------------- | --------- | -------- | -------------------------------------------- |
58+
| `easingFactor` | `number` | `0.1` | Easing factor for smooth movement (0.01-0.5) |
59+
| `updateInterval` | `number` | `15` | Update interval in milliseconds (5-50) |
60+
| `size` | `number` | `14` | Size of the cursor element in pixels (5-50) |
61+
| `color` | `string` | `"#fff"` | Color of the cursor element |
62+
| `borderRadius` | `string` | `"100%"` | Border radius for shape customization |
63+
| `zIndex` | `number` | `9999` | Z-index for stacking order |
64+
| `hideCursor` | `boolean` | `true` | Whether to hide the default browser cursor |
65+
| `fadeDuration` | `number` | `200` | Fade transition duration in milliseconds |
66+
| `fadeDistance` | `number` | `10` | Distance from edges where fading starts |
6667

6768
## Advanced Usage
6869

69-
### Custom Color Gradients
70+
### Custom Styling
71+
72+
```tsx
73+
useCursorFollow({
74+
color: "#ff6b6b",
75+
size: 20,
76+
borderRadius: "50%",
77+
easingFactor: 0.15,
78+
updateInterval: 10,
79+
});
80+
```
81+
82+
### Square Cursor
83+
84+
```tsx
85+
useCursorFollow({
86+
color: "#4ecdc4",
87+
size: 16,
88+
borderRadius: "4px",
89+
hideCursor: true,
90+
});
91+
```
92+
93+
### Performance Optimized
94+
95+
```tsx
96+
useCursorFollow({
97+
easingFactor: 0.2,
98+
updateInterval: 8,
99+
size: 8,
100+
fadeDuration: 100,
101+
});
102+
```
103+
104+
### Keep Default Cursor
105+
106+
```tsx
107+
useCursorFollow({
108+
color: "#ffd93d",
109+
hideCursor: false, // Keep the default cursor visible
110+
zIndex: 1000,
111+
});
112+
```
113+
114+
## Examples
115+
116+
### Basic Red Cursor
117+
118+
```tsx
119+
useCursorFollow({ color: "red" });
120+
```
121+
122+
### Large Smooth Cursor
123+
124+
```tsx
125+
useCursorFollow({
126+
color: "#ff6b6b",
127+
size: 25,
128+
easingFactor: 0.05,
129+
updateInterval: 10,
130+
});
131+
```
132+
133+
### Fast Small Cursor
70134

71135
```tsx
72-
// Two-color gradient
73-
<GradientHover colors={["#667eea", "#764ba2"]}>
74-
<div>Your content</div>
75-
</GradientHover>
76-
77-
// Multi-color gradient
78-
<GradientHover colors={["#ff6b6b", "#4ecdc4", "#45b7d1"]}>
79-
<div>Your content</div>
80-
</GradientHover>
136+
useCursorFollow({
137+
color: "#00d4ff",
138+
size: 8,
139+
easingFactor: 0.2,
140+
updateInterval: 8,
141+
});
81142
```
82143

83-
### Animation Control
144+
### Square Cursor with Edge Fading
84145

85146
```tsx
86-
<GradientHover
87-
animationSpeed={7}
88-
transitionDuration={0.5}
89-
shouldAlwaysShowGradient={false}
90-
>
91-
<div>Your content</div>
92-
</GradientHover>
147+
useCursorFollow({
148+
color: "#ffd93d",
149+
size: 16,
150+
borderRadius: "4px",
151+
fadeDistance: 20,
152+
fadeDuration: 300,
153+
});
93154
```
94155

95156
## Browser Support
96157

97-
The component utilizes modern CSS features including:
158+
The hook utilizes modern web APIs including:
98159

99-
- CSS Custom Properties (CSS Variables)
100-
- `requestAnimationFrame` API
101-
- Standard CSS positioning and transforms
160+
- `requestAnimationFrame` for smooth animations
161+
- CSS transitions for fade effects
162+
- Standard DOM event handling
163+
- CSS positioning and transforms
102164

103165
Ensure your target browsers support these features or include appropriate polyfills.
104166

@@ -136,9 +198,7 @@ Ensure your target browsers support these features or include appropriate polyfi
136198

137199
### Documentation
138200

139-
View the interactive documentation and examples at [https://areknow.github.io/react-gradient-hover/](https://areknow.github.io/react-gradient-hover/)
140-
141-
To run the documentation locally:
201+
View the interactive documentation and examples:
142202

143203
```bash
144204
npm run styleguide
@@ -153,7 +213,6 @@ Before publishing a new version, ensure you complete the following checklist:
153213
- [ ] TypeScript compilation succeeds (`npm run typecheck`)
154214
- [ ] Documentation is up to date
155215
- [ ] Version number is appropriate for changes (following semver)
156-
- [ ] Changelog is updated
157216
- [ ] Git working directory is clean
158217

159218
#### Testing the Package Locally
@@ -171,7 +230,7 @@ Before publishing to npm, it's recommended to test the package locally:
171230

172231
```bash
173232
cd ../your-test-project
174-
npm install ../react-gradient-hover/react-gradient-hover-x.y.z.tgz
233+
npm install ../react-use-cursor-follow/react-use-cursor-follow-x.y.z.tgz
175234
```
176235

177236
3. Verify the package works as expected in your test project
@@ -198,24 +257,6 @@ Before publishing to npm, it's recommended to test the package locally:
198257
git push && git push --tags
199258
```
200259

201-
#### Troubleshooting
202-
203-
If publishing fails:
204-
205-
- Ensure you're logged in: `npm whoami`
206-
- Verify you have publish permissions: `npm access ls-packages`
207-
- Check that the package name is available: `npm view react-gradient-hover`
208-
209-
For build errors:
210-
211-
- Verify all dependencies are installed
212-
- Check TypeScript and Rollup configurations
213-
- Review the build logs for specific errors
214-
215-
## Contributing
216-
217-
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.
218-
219260
## License
220261

221-
[MIT](LICENSE) © [areknow](https://github.com/areknow)
262+
MIT © [areknow](https://github.com/areknow)

0 commit comments

Comments
 (0)