{"id":29122307,"url":"https://github.com/phucbm/magnetic-button","last_synced_at":"2025-06-29T17:10:23.047Z","repository":{"id":300895364,"uuid":"1007488494","full_name":"phucbm/magnetic-button","owner":"phucbm","description":"A lightweight TypeScript library that creates smooth magnetic attraction effects for HTML elements","archived":false,"fork":false,"pushed_at":"2025-06-24T06:23:08.000Z","size":32,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-24T06:30:20.262Z","etag":null,"topics":["animation","button","hover","interaction","magnetic","typescript","ui"],"latest_commit_sha":null,"homepage":"https://phucbm.github.io/magnetic-button/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/phucbm.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-24T04:46:18.000Z","updated_at":"2025-06-24T06:23:11.000Z","dependencies_parsed_at":"2025-06-24T06:30:49.444Z","dependency_job_id":"83c3d827-b078-493a-a900-53285196d796","html_url":"https://github.com/phucbm/magnetic-button","commit_stats":null,"previous_names":["phucbm/magnetic-button"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/phucbm/magnetic-button","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phucbm%2Fmagnetic-button","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phucbm%2Fmagnetic-button/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phucbm%2Fmagnetic-button/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phucbm%2Fmagnetic-button/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/phucbm","download_url":"https://codeload.github.com/phucbm/magnetic-button/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phucbm%2Fmagnetic-button/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262632328,"owners_count":23340214,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["animation","button","hover","interaction","magnetic","typescript","ui"],"created_at":"2025-06-29T17:10:14.086Z","updated_at":"2025-06-29T17:10:23.036Z","avatar_url":"https://github.com/phucbm.png","language":"TypeScript","readme":"# 🧲 Magnetic Button\n\nA lightweight TypeScript library that creates smooth magnetic attraction effects for HTML elements. Elements with\nthe `data-magnetic` attribute will gently follow the mouse cursor when it's nearby, creating an engaging hover\ninteraction.\n\n[![npm version](https://badgen.net/npm/v/@phucbm/magnetic-button?icon=npm)](https://www.npmjs.com/package/@phucbm/magnetic-button)\n[![npm downloads](https://badgen.net/npm/dm/@phucbm/magnetic-button?icon=npm)](https://www.npmjs.com/package/@phucbm/magnetic-button)\n[![npm downloads](https://badgen.net/npm/dependents/@phucbm/magnetic-button?icon=npm)](https://www.npmjs.com/package/@phucbm/magnetic-button)\n[![jsdelivr hits](https://badgen.net/jsdelivr/hits/gh/phucbm/magnetic-button?icon=jsdelivr)](https://www.jsdelivr.com/package/gh/phucbm/magnetic-button)\n[![GitHub release](https://badgen.net/jsdelivr/rank/npm/@phucbm/magnetic-button?icon=jsdelivr)](https://github.com/phucbm/magnetic-button/releases)\n[![pages-build-deployment](https://github.com/phucbm/magnetic-button/actions/workflows/pages/pages-build-deployment/badge.svg)](https://github.com/phucbm/magnetic-button/actions/workflows/pages/pages-build-deployment)\n[![Publish on Release](https://github.com/phucbm/magnetic-button/actions/workflows/publish-on-release.yml/badge.svg)](https://github.com/phucbm/magnetic-button/actions/workflows/publish-on-release.yml)\n[![license](https://badgen.net/github/license/phucbm/magnetic-button?icon=github)](https://github.com/phucbm/magnetic-button/blob/main/LICENSE)\n[![Made in Vietnam](https://raw.githubusercontent.com/webuild-community/badge/master/svg/made.svg)](https://webuild.community)\n\n## ✨ Features\n\n- **Zero dependencies** - Lightweight and fast\n- **TypeScript support** - Full type definitions included\n- **Auto-initialization** - Works with data attributes out of the box\n- **Customizable** - Fine-tune distance, attraction, and animation speed\n- **Smooth animations** - Uses linear interpolation for buttery smooth movement\n- **Event callbacks** - Hook into enter, exit, and update events\n- **Modern browsers** - Works in all modern browsers that support ES2022\n\n## 🚀 Demo\n\nCheck out the [live demo](https://phucbm.github.io/magnetic-button/) to see the magnetic effect in action!\n\n## 📦 Installation\n\n### npm\n\n```bash\nnpm install @phucbm/magnetic-button\n```\n\n### pnpm\n\n```bash\npnpm add @phucbm/magnetic-button\n```\n\n### yarn\n\n```bash\nyarn add @phucbm/magnetic-button\n```\n\n### CDN\n\n```html\n\n\u003cscript type=\"module\"\u003e\n    import {MagneticButton} from 'https://unpkg.com/@phucbm/magnetic-button/dist/index.js'\n\n    new MagneticButton()\n\u003c/script\u003e\n```\n\n```html\n\n\u003cscript src=\"https://unpkg.com/@phucbm/magnetic-button/dist/magnetic-button.js\"\u003e\u003c/script\u003e\n\u003cscript\u003e\n    // MagneticButton is available on the window object\n    const magnetic = new window.MagneticButton()\n\u003c/script\u003e\n\n```\n\n## 🎯 Quick Start\n\n### HTML + Data Attributes (Easiest)\n\n```html\n\u003c!DOCTYPE html\u003e\n\u003chtml\u003e\n\u003chead\u003e\n    \u003cstyle\u003e\n        .magnetic-btn {\n            padding:1rem 2rem;\n            border:2px solid #333;\n            background:#1a1a1a;\n            color:white;\n            border-radius:8px;\n            cursor:pointer;\n            transition:border-color 0.3s ease;\n        }\n\n        .magnetic-btn.magnetizing {\n            border-color:#ff6b6b;\n            box-shadow:0 0 20px rgba(255, 107, 107, 0.3);\n        }\n    \u003c/style\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n\u003c!-- Basic usage --\u003e\n\u003cbutton class=\"magnetic-btn\" data-magnetic\u003e\n    Hover me!\n\u003c/button\u003e\n\n\u003c!-- With custom parameters --\u003e\n\u003cbutton\n        class=\"magnetic-btn\"\n        data-magnetic\n        data-distance=\"150\"\n        data-attraction=\"0.3\"\n        data-fraction=\"0.2\"\u003e\n    Custom magnetic button\n\u003c/button\u003e\n\n\u003cscript type=\"module\"\u003e\n    import {MagneticButton} from '@phucbm/magnetic-button'\n\n    new MagneticButton() // Auto-initializes all elements with data-magnetic\n\u003c/script\u003e\n\u003c/body\u003e\n\u003c/html\u003e\n```\n\n### JavaScript/TypeScript\n\n```typescript\nimport {MagneticButton} from '@phucbm/magnetic-button'\n\n// Auto-initialize all elements with data-magnetic attribute\nnew MagneticButton()\n\n// Or target a specific element\nconst button = document.querySelector('.my-button')\nnew MagneticButton(button, {\n    distance: 200,\n    attraction: 0.5,\n    fraction: 0.1,\n    onEnter: (data) =\u003e console.log('Magnetized!', data),\n    onExit: (data) =\u003e console.log('Released!', data)\n})\n```\n\n## ⚙️ Configuration Options\n\n### Data Attributes\n\nAdd these attributes to your HTML elements to customize the magnetic effect:\n\n| Attribute         | Type     | Default | Description                                               |\n|-------------------|----------|---------|-----------------------------------------------------------|\n| `data-magnetic`   | -        | -       | **Required**. Enables magnetic effect on the element      |\n| `data-distance`   | `number` | `200`   | Range within which the magnetic effect is active (pixels) |\n| `data-attraction` | `number` | `0.3`   | Strength of magnetic pull (0 = strong, 1 = weak)          |\n| `data-fraction`   | `number` | `0.1`   | Speed of magnetic movement (0 = instant, 1 = slow)        |\n\n### JavaScript Options\n\nWhen initializing with JavaScript, you can pass these options:\n\n| Option        | Type       | Default         | Description                                           |\n|---------------|------------|-----------------|-------------------------------------------------------|\n| `activeClass` | `string`   | `'magnetizing'` | CSS class added when magnetic effect is active        |\n| `attraction`  | `number`   | `0.3`           | Strength of magnetic pull (0 = strong, 1 = weak)      |\n| `distance`    | `number`   | `200`           | Range within which magnetic effect is active (pixels) |\n| `fraction`    | `number`   | `0.1`           | Speed of magnetic movement (0 = instant, 1 = slow)    |\n| `onEnter`     | `function` | `() =\u003e {}`      | Callback fired when mouse enters magnetic area        |\n| `onExit`      | `function` | `() =\u003e {}`      | Callback fired when mouse exits magnetic area         |\n| `onUpdate`    | `function` | `() =\u003e {}`      | Callback fired continuously while in magnetic area    |\n\n## 🎭 CSS Classes\n\nThe library automatically adds CSS classes that you can style:\n\n| Class            | When Applied | Description                                                                       |\n|------------------|--------------|-----------------------------------------------------------------------------------|\n| `.is-magnetized` | Always       | Added to all magnetic elements for identification                                 |\n| `.magnetizing`   | On hover     | Added when mouse is within magnetic range (customizable via `activeClass` option) |\n\n## 📋 API Reference\n\n### Constructor\n\n```typescript\nnew MagneticButton(target ? : HTMLElement | null, options ? : MagneticButtonOptions)\n```\n\n**Parameters:**\n\n- `target` - The HTML element to apply magnetic effect to. If `null` or omitted, auto-initializes all elements\n  with `data-magnetic` attribute\n- `options` - Configuration options (see table above)\n\n### Event Data\n\nCallback functions receive a `MagneticData` object with the following properties:\n\n| Property   | Type     | Description                               |\n|------------|----------|-------------------------------------------|\n| `deltaX`   | `number` | Horizontal offset from element center     |\n| `deltaY`   | `number` | Vertical offset from element center       |\n| `distance` | `number` | Distance between mouse and element center |\n\n## 🎨 Examples\n\n### Strong Attraction\n\n```html\n\n\u003cbutton data-magnetic data-distance=\"120\" data-attraction=\"0.1\"\u003e\n    Strong Pull\n\u003c/button\u003e\n```\n\n### Subtle Effect\n\n```html\n\n\u003cbutton data-magnetic data-distance=\"80\" data-attraction=\"0.8\" data-fraction=\"0.05\"\u003e\n    Subtle Movement\n\u003c/button\u003e\n```\n\n### Large Detection Area\n\n```html\n\n\u003cbutton data-magnetic data-distance=\"300\" data-attraction=\"0.4\"\u003e\n    Wide Range\n\u003c/button\u003e\n```\n\n### With Event Callbacks\n\n```typescript\nnew MagneticButton(document.querySelector('.special-btn'), {\n    distance: 150,\n    attraction: 0.3,\n    onEnter: (data) =\u003e {\n        console.log('Entered magnetic field!')\n        // Play sound, trigger animation, etc.\n    },\n    onExit: (data) =\u003e {\n        console.log('Left magnetic field!')\n        // Reset state, stop animation, etc.\n    },\n    onUpdate: (data) =\u003e {\n        // Update UI based on mouse position\n        if (data.distance \u003c 50) {\n            console.log('Very close to button!')\n        }\n    }\n})\n```\n\n## 🎯 Tips and Best Practices\n\n### Performance\n\n- The library is optimized and uses `requestAnimationFrame` internally\n- Avoid initializing too many magnetic elements simultaneously (recommended max: ~20-30)\n\n### CSS Styling\n\n```css\n/* Smooth transitions for non-magnetic properties */\n.magnetic-btn {\n    transition:border-color 0.3s ease, box-shadow 0.3s ease;\n}\n\n/* Active state styling */\n.magnetic-btn.magnetizing {\n    border-color:#ff6b6b;\n    box-shadow:0 0 20px rgba(255, 107, 107, 0.3);\n}\n\n/* Ensure transform doesn't interfere with other transforms */\n.magnetic-btn {\n    transform-origin:center;\n}\n```\n\n### Accessibility\n\nThe magnetic effect doesn't interfere with keyboard navigation or screen readers, making it accessible by default.\n\n### Framework Integration\n\n**React:**\n\n```jsx\nimport {useEffect, useRef} from 'react'\nimport {MagneticButton} from '@phucbm/magnetic-button'\n\nfunction MyButton(){\n    const buttonRef = useRef(null)\n\n    useEffect(() =\u003e {\n        const magnetic = new MagneticButton(buttonRef.current, {\n            distance: 150,\n            attraction: 0.3\n        })\n    }, [])\n\n    return \u003cbutton ref={buttonRef}\u003eMagnetic Button\u003c/button\u003e\n}\n```\n\n**Vue:**\n\n```vue\n\n\u003ctemplate\u003e\n  \u003cbutton ref=\"buttonRef\"\u003eMagnetic Button\u003c/button\u003e\n\u003c/template\u003e\n\n\u003cscript setup\u003e\n  import {ref, onMounted} from 'vue'\n  import {MagneticButton} from '@phucbm/magnetic-button'\n\n  const buttonRef = ref(null)\n\n  onMounted(() =\u003e {\n    new MagneticButton(buttonRef.value, {\n      distance: 150,\n      attraction: 0.3\n    })\n  })\n\u003c/script\u003e\n```\n\n## 🌐 Browser Support\n\n- Chrome 63+\n- Firefox 61+\n- Safari 13.1+\n- Edge 79+\n\n## 📄 License\n\nMIT © [phucbm](https://github.com/phucbm)\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## 🔗 Links\n\n- [GitHub Repository](https://github.com/phucbm/magnetic-button)\n- [Live Demo](https://phucbm.github.io/magnetic-button/)\n- [npm Package](https://www.npmjs.com/package/@phucbm/magnetic-button)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphucbm%2Fmagnetic-button","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphucbm%2Fmagnetic-button","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphucbm%2Fmagnetic-button/lists"}