magnetic-links-gsap

A configurable magnetic-pull hover effect for links, buttons, and nav items — built on GSAP.

Two layers move independently: the element itself pulls toward the cursor, and the content inside it pulls slightly more, creating the parallax feel used on a lot of high-end agency sites.

Install

npm install magnetic-links-gsap gsap

gsap is a peer dependency — you bring your own version, so the package stays tiny and never conflicts with a GSAP install you already have (including GSAP plugins/ScrollTrigger elsewhere in your project).

Usage

import { createMagneticLinks } from 'magnetic-links-gsap';

createMagneticLinks('.magnetic-link', {
  strength: 0.4,       // how far the element itself moves, 0–1
  innerStrength: 0.65, // how far the inner text/icon moves — keep higher than `strength`
  tilt: 8,             // subtle rotation in degrees as it moves horizontally
});

Works with a selector string, a single element, or a list of elements:

createMagneticLinks(document.querySelector('#cta'), {
  strength: 0.5,
  radius: 100,       // activates within 100px of the element, not just on direct hover
  hoverScale: 1.06,  // gentle scale bump while active
});

Cleanup (SPAs / React / Vue)

const instance = createMagneticLinks('.magnetic-link');
// later, e.g. on unmount:
instance.destroy();

Options

| Option | Default | Description | |---|---|---| | strength | 0.4 | How far the element moves toward the cursor (0–1) | | innerStrength | 0.65 | How far the inner content moves — the parallax layer | | radius | undefined | Activation radius in px from center. Omit to require direct hover | | duration | 0.5 | Follow tween duration (seconds) | | ease | 'power3.out' | Ease while following the cursor | | releaseDuration | 0.9 | Snap-back tween duration on mouse leave | | releaseEase | 'elastic.out(1, 0.4)' | Snap-back ease — this is what gives the "magnetic" feel | | hoverScale | 1 | Optional scale-up while active | | tilt | 0 | Optional subtle rotation (degrees) based on horizontal pull | | innerSelector | undefined | Custom selector for the inner moving layer (auto-wraps content if omitted) |

Demo

Open demo/index.html after running npm run build to see it live — one example using direct-hover activation, one using radius-based activation with a scale bump.

Publishing

GitHub (so people can find it, star it, file issues, contribute):

1. Create a new repo on GitHub, then from this folder:

   git init
   git add .
   git commit -m "Initial commit"
   git branch -M main
   git remote add origin https://github.com/hunterrei/magnetic-links-gsap.git
   git push -u origin main

2. Replace hunterrei in package.json with your actual GitHub username.
3. Add repo topics on GitHub (Settings → General → Topics) like gsap, animation, hover-effect — this is how people find it via search/browsing.

npm (so people can npm install it):

1. Update the name in package.json if magnetic-links-gsap is taken (check with npm view magnetic-links-gsap).
2. npm login
3. npm run build
4. npm publish --access public

Automated publishing (recommended): .github/workflows/publish.yml is already set up to publish to npm automatically whenever you push a version tag (git tag v0.1.1 && git push --tags). It needs an NPM_TOKEN secret:

1. Generate an npm access token: npmjs.com → your avatar → Access Tokens → Generate New Token → "Automation" type.
2. On GitHub: repo → Settings → Secrets and variables → Actions → New repository secret → name it NPM_TOKEN, paste the token.
3. From then on, bump the version in package.json, commit, tag it, push the tag — CI builds and publishes for you. No more manual npm publish.

There's also a .github/workflows/ci.yml that builds the package on every push/PR to main, so a broken build gets caught before you ever tag a release.

License

MIT