magnetic-hover.js
v1.0.0
Published
Lightweight magnetic text hover effect animation library
Downloads
7
Maintainers
tizeeReadme
magnetic-hover.js
A lightweight, non-intrusive magnetic text hover effect animation library. When the mouse hovers over text, characters dynamically adjust their scale, stroke width, and padding based on distance, creating a magnetic field-like visual effect.
🆓 Completely Open Source & Free - An open-source alternative to paid framer-motion versions, providing the same effect
✨ Features
- Pure JavaScript - No dependencies, compatible with modern browsers
- Lightweight - Only ~5KB minified
magnetic-hover.min.js - Completely Free - MIT license, alternative to paid versions
- Non-intrusive - Doesn't modify existing styles, plug-and-play
- High Performance - Optimized with RAF and throttling, smooth 60fps animation
- Configurable - Rich configuration options for different needs
- TypeScript - Complete type definition support
🚀 Quick Start
Installation
# npm
npm install magnetic-hover.js
# yarn
yarn add magnetic-hover.js
# Or use CDN directly
<script src="https://unpkg.com/magnetic-hover.js/dist/magnetic-hover.min.js"></script>Basic Usage
<!DOCTYPE html>
<html>
<head>
<style>
.magtext {
font-size: 4rem;
font-family: system-ui, sans-serif;
}
</style>
</head>
<body>
<h1 class="magtext">MAGNETIC HOVER</h1>
<script src="magnetic-hover.min.js"></script>
<script>
// Initialize
new MagneticHover('.magtext');
</script>
</body>
</html>ES Module
import MagneticHover from 'magnetic-hover.js';
// Basic usage
const magneticText = new MagneticHover('.magtext');
// With configuration
const magneticText = new MagneticHover('.magtext', {
maxScaleX: 1.12,
minScaleX: 1.0,
maxScaleY: 1.0,
minScaleY: 0.9,
effectRadius: 120,
smoothing: 0.12,
});⚙️ Configuration Options
new MagneticHover('.magtext', {
maxScaleX: 1.12, // Maximum X scale factor (stretch)
minScaleX: 1.0, // Minimum X scale factor
maxScaleY: 1.0, // Maximum Y scale factor (normal height)
minScaleY: 0.9, // Minimum Y scale factor (compress)
maxStroke: 0.1, // Maximum text stroke width (em)
minStroke: 0, // Minimum text stroke width (em)
maxPaddingInline: 0.1, // Maximum padding-inline (em)
minPaddingInline: 0, // Minimum padding-inline (em)
effectRadius: 120, // Effect radius in pixels
smoothing: 0.12, // Smoothing factor (0-1), higher = faster change
charClassName: 'maghover-char', // Character element CSS class name
throttleDelay: 16, // Throttle delay (milliseconds)
});📚 API Documentation
Methods
start()
Start animation effect
magneticText.start();stop()
Stop animation effect
magneticText.stop();restart()
Restart animation
magneticText.restart();updateOptions(options)
Update configuration options
magneticText.updateOptions({
effectRadius: 200,
maxScaleX: 1.2,
maxStroke: 0.15,
});destroy()
Destroy instance, restore original text, clean up event listeners
magneticText.destroy();Static Properties
MagneticHover.version
Get library version
console.log(MagneticHover.version); // "1.0.0"🎯 Usage Examples
Multiple Elements
// Apply to multiple elements simultaneously
new MagneticHover('.title, .subtitle', {
maxScaleX: 1.08,
effectRadius: 100,
});Dynamic Control
const magneticText = new MagneticHover('.magtext');
// Start on mouse enter
document.addEventListener('mouseenter', () => {
magneticText.start();
});
// Stop on mouse leave
document.addEventListener('mouseleave', () => {
magneticText.stop();
});🎨 Style Recommendations
For best results, we recommend:
.magtext {
/* Use fonts that support multiple weights */
font-family:
system-ui,
-apple-system,
BlinkMacSystemFont,
sans-serif;
/* Set appropriate font size */
font-size: clamp(2rem, 6vw, 8rem);
/* Disable text selection */
user-select: none;
/* Appropriate letter spacing */
letter-spacing: 0.05em;
}🌐 Browser Compatibility
- Chrome 60+
- Firefox 60+
- Safari 12+
- Edge 79+
Supports all modern browsers, uses CSS transform, stroke, and padding properties for dynamic effects.
📦 Build
# Install dependencies
just install
# Build production version
just build
# Development mode (watch for file changes)
just dev
# Format code
just format
# Full rebuild (clean + install + build)
just rebuild
# Check project health
just check🔧 Development
The project uses esbuild for building, keeping it simple and efficient:
magnetic-hover.js/
├── src/
│ └── magnetic-hover.js # Source code
├── dist/
│ ├── magnetic-hover.min.js # Minified version
│ ├── magnetic-hover.esm.js # ES Module
│ └── magnetic-hover.d.ts # TypeScript definitions
├── build.js # Build script
└── package.json🤝 Contributing
Issues and Pull Requests are welcome!
📄 License
🙏 Acknowledgments
Inspired by magnetic interaction effects in modern web design, committed to providing developers with a simple and easy-to-use text animation solution. This open-source alternative makes cool text animation effects accessible to more developers.