A React component that creates an interactive gradient effect following mouse movement on hover
npm install react-gradient-hoverA high-performance React component that creates an elegant, interactive gradient effect that follows cursor movement. Perfect for creating engaging interactive hover states.



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.
- 🎨 Fluid gradient animations using requestAnimationFrame
- 🌈 Support for multiple gradient colors (minimum of 2)
- âš¡ Optimized performance with debounced event handling
- 🎯 Customizable animation speed and transition duration
- 📱 Responsive design with automatic resizing
- 🔧 TypeScript support with comprehensive type definitions
``bash`
npm install react-gradient-hover
or
`bash`
yarn add react-gradient-hover
`tsx
import { GradientHover } from "react-gradient-hover";
function App() { Hover to see the effect in action
return (
Interactive Gradient
);
}
`
| Prop | Type | Default | Description |
| -------------------------- | --------------- | ------------------------ | ------------------------------------------- |
| colors | string[] | ['#EB2DD2', '#5AB5EE'] | Array of gradient colors (minimum 2) |children
| | ReactNode | Required | Content to wrap with the gradient effect |className
| | string | '' | Additional CSS class names |style
| | CSSProperties | {} | Additional inline styles |onClick
| | () => void | - | Optional click handler |animationSpeed
| | number | 5 | Animation speed (1-10, where 10 is fastest) |transitionDuration
| | number | 1 | Transition duration in seconds |shouldAlwaysShowGradient
| | boolean | true | Whether to show gradient before hover |
`tsx
// Two-color gradient
Your content
// Multi-color gradient
Your content
`
`tsx`
transitionDuration={0.5}
shouldAlwaysShowGradient={false}
>
Your content
The component utilizes modern CSS features including:
- CSS Custom Properties (CSS Variables)
- requestAnimationFrame API
- Standard CSS positioning and transforms
Ensure your target browsers support these features or include appropriate polyfills.
- Node.js (version 16 or higher)
- npm or yarn
1. Install dependencies:
`bash`
npm install
2. Start development server:
`bash`
npm run dev
3. Run tests:
`bash`
npm test
4. Build the package:
`bash`
npm run build
View the interactive documentation and examples:
`bash`
npm run styleguide
Before publishing a new version, ensure you complete the following checklist:
- [ ] All tests pass (npm test)npm run lint
- [ ] Code is linted ()npm run typecheck
- [ ] TypeScript compilation succeeds ()
- [ ] Documentation is up to date
- [ ] Version number is appropriate for changes (following semver)
- [ ] Changelog is updated
- [ ] Git working directory is clean
#### Testing the Package Locally
Before publishing to npm, it's recommended to test the package locally:
1. Create a test package:
`bash`
npm pack --dry-run # List the files that will be included
npm pack # Create the tarball
2. Test in another project:
`bash`
cd ../your-test-project
npm install ../react-gradient-hover/react-gradient-hover-x.y.z.tgz
3. Verify the package works as expected in your test project
#### Publishing Steps
1. Update the version:
`bash`
npm version patch # for bug fixes (1.0.0 -> 1.0.1)
npm version minor # for new features (1.0.0 -> 1.1.0)
npm version major # for breaking changes (1.0.0 -> 2.0.0)
2. Build and publish:
`bash`
npm run build
npm publish
3. Push changes and tags:
`bash`
git push && git push --tags
#### Troubleshooting
If publishing fails:
- Ensure you're logged in: npm whoaminpm access ls-packages
- Verify you have publish permissions: npm view react-gradient-hover`
- Check that the package name is available:
For build errors:
- Verify all dependencies are installed
- Check TypeScript and Rollup configurations
- Review the build logs for specific errors
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.