🧲 magneticui

Ultra-lightweight, zero-dependency high-performance magnetic cursor pull micro-library for web UI with 0KB external assets.

Live Demo: https://magneticui.vercel.app

⚡ Why magneticui?

High-end award-winning web UI (Apple, Stripe, Raycast, Awwwards portfolios) uses magnetic cursor attraction on buttons, icons, avatars, and cards. However, existing spring physics libraries are heavy (30KB–80KB) or introduce layout shifts and high CPU overhead.

magneticui is a < 1.8 KB gzipped zero-dependency micro-engine. It calculates smooth damped harmonic spring physics (transform: translate3d(x, y)), supports multi-layered 3D depth for child elements, and automatically pauses animation loops when idle.

• 🧲 Multi-Layered 3D Depth: Displace child elements (icons, text) separately for 3D depth!
• ⚡ Zero Layout Shift: Transforms elements strictly via GPU-accelerated translate3d().
• 💤 Zero Idle Overhead: requestAnimationFrame spring loop automatically pauses when idle or outside radius threshold.
• 🪶 Micro Footprint: Under 1.8 KB gzipped!
• ⚛️ React & Vanilla JS: Works everywhere (React <Magnetic>, Next.js App Router, Vue, Svelte, or plain JS).

📦 Installation

npm install magneticui
# or
pnpm add magneticui
# or
yarn add magneticui

🚀 Quick Start

1. Vanilla JS / TypeScript

import { magnetic } from 'magneticui';

// Attach magnetic button preset
magnetic.button(document.querySelector('#cta-btn'));

// Or custom magnetic pull with 3D depth for nested icon
magnetic.attach(document.querySelector('#card'), {
  radius: 90,
  strength: 0.35,
  childSelector: '.card-icon',
  childStrength: 1.2
});

// Presets
magnetic.icon(el);
magnetic.avatar(el);
magnetic.card(el);
magnetic.text(el);
magnetic.strong(el);

2. React / Next.js App Router (<Magnetic> & useMagnetic)

[!TIP] magneticui is 100% SSR-safe. In Next.js App Router (Next.js 13/14/15/16), simply use 'use client' on components importing UI hooks.

'use client';

import React from 'react';
import { Magnetic } from 'magneticui/react';

export function ActionButton() {
  return (
    <Magnetic radius={90} strength={0.4} childSelector=".inner-icon" childStrength={1.2}>
      <button className="cta-btn">
        <span className="inner-icon">⭐</span>
        <span>Magnetic Action</span>
      </button>
    </Magnetic>
  );
}

🎛️ 6 Built-in Presets Matrix

| Preset Method | Radius | Pull Strength | Damping / Elasticity | Use Case | | :--- | :--- | :--- | :--- | :--- | | magnetic.button() | 80px | 0.35 | Smooth snap back | Primary CTA buttons, Submit actions | | magnetic.icon() | 60px | 0.50 | High elasticity spring | Social icons, toolbar buttons | | magnetic.avatar() | 100px | 0.25 | Gentle float | Profile avatars, user badges | | magnetic.card() | 120px | 0.15 | Subtly weighted drift | Feature cards, pricing boxes | | magnetic.text() | 60px | 0.30 | Inner child text shift | Nested text labels inside buttons | | magnetic.strong() | 90px | 0.70 | Ultra-reactive magnet | Interactive game items, widgets |

🧪 Custom Physics API Options

import { magnetic } from 'magneticui';

magnetic.attach(element, {
  radius: 100,          // Magnetic threshold radius in px (default: 80)
  strength: 0.4,        // Pull strength multiplier (default: 0.35)
  stiffness: 160,       // Spring stiffness coefficient (default: 150)
  damping: 15,          // Spring damping coefficient (default: 15)
  mass: 1.0,            // Element mass (default: 1.0)
  childSelector: '.icon', // Selector for nested 3D child element
  childStrength: 1.2,   // Magnetic multiplier for nested child element
  mobile: false         // Disable magnetic pull on mobile touch screens
});

📄 License

MIT © fullstackusama