magnetic-hover.js
Version:
Lightweight magnetic text hover effect animation library
269 lines (196 loc) • 6.32 kB
Markdown
# magnetic-hover.js
[](https://github.com/tizee/magnetic-hover.js/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/magnetic-hover.js)
[](https://opensource.org/licenses/MIT)
[](https://bundlephobia.com/package/magnetic-hover.js)
[](https://www.typescriptlang.org/)
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
```bash
# 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
```html
<!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
```javascript
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
```javascript
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
```javascript
magneticText.start();
```
#### `stop()`
Stop animation effect
```javascript
magneticText.stop();
```
#### `restart()`
Restart animation
```javascript
magneticText.restart();
```
#### `updateOptions(options)`
Update configuration options
```javascript
magneticText.updateOptions({
effectRadius: 200,
maxScaleX: 1.2,
maxStroke: 0.15,
});
```
#### `destroy()`
Destroy instance, restore original text, clean up event listeners
```javascript
magneticText.destroy();
```
### Static Properties
#### `MagneticHover.version`
Get library version
```javascript
console.log(MagneticHover.version); // "1.0.0"
```
## 🎯 Usage Examples
### Multiple Elements
```javascript
// Apply to multiple elements simultaneously
new MagneticHover('.title, .subtitle', {
maxScaleX: 1.08,
effectRadius: 100,
});
```
### Dynamic Control
```javascript
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:
```css
.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
```bash
# 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
[MIT License](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.