cta · HTML and CSS
MagneticButton
Buttons and links that lean gently towards the pointer, so the main action feels within reach.
Magnetic spring wrapper for buttons and links with fine-pointer gating
- HTML and CSS
- Reduced motion: static
- 1.88 KB gzip
- Layout shift 0
Install
pnpm dlx shadcn@4.21.1 add @frictionborn/magnetic-button
Playground
Move the pointer near the button. Fine pointers only; nothing moves with reduced motion.
import { MagneticButton } from "@/components/ui/magnetic-button";
<MagneticButton>
<button type="button">Start a project</button>
</MagneticButton>In a full example
The full example loads as you scroll to it.
Accessibility
- The wrapped button or link keeps its native semantics. The wrapper div uses overflow: visible so it does not clip focus rings, and keyboard focus immediately resets translation to origin.
- Keyboard: Focus snaps the wrapper to its origin immediately and the child's own onFocus still runs; the wrapper uses overflow: visible
- Touch: Zero pointer handlers attached on coarse/touch screens
- WCAG criteria it is built for: 2.1.1, 2.4.7, 2.5.3
Props
| Prop | Type | Default | What it does |
|---|---|---|---|
children | React.ReactElement | none | Required. A single interactive element (button or link) wrapped by the magnetic controller. |
pullDistance | number | 16 | Maximum pull translation in pixels (replaces deprecated strength). |
paused | boolean | false | Universal pause prop. Freezes magnetic displacement calculation. |
tension | number | 180 | Spring stiffness coefficient. |
damping | number | 16 | Spring velocity damping coefficient. |
className | string | "" | Additional CSS classes applied to the outer wrapper div (the built-in class fb-magnetic-button is kept). |
style | React.CSSProperties | none | Optional. No default. Inline styles on the wrapper div, merged after display: inline-block and position: relative (consumer wins). |
ref | React.Ref<HTMLDivElement> | none | Receives the wrapper <div> (not the child button). |
maxTier | number | 3 | Hard ceiling on the capability tier. |
Measured on the bench
Measured by the automated bench at commit 801163e on 2026-10-21. These numbers are written by the bench, never by hand.
| Measure | Result |
|---|---|
| Size, gzip | 1.88 KB at load, 0.02 KB loaded later |
| Layout shift | 0 |
| Frames when nothing should move | off screen 0, hidden tab 0, reduced motion 0 |
| axe accessibility scan | 0 serious, 0 critical |
Browsers it ran in
Automated Playwright runs, some with device emulation. Results from physical phones and tablets are still pending, so none are listed.
| Environment | Tier | Result | Date | Notes |
|---|---|---|---|---|
| Chromium Desktop (SwiftShader) | 3 | pass | 2026-10-21 | 14 passed, 0 failed |
| Chromium Mobile (Pixel 7 emulation) | 2 | pass | 2026-10-21 | 13 passed, 0 failed |
| Firefox Desktop | 3 | pass | 2026-10-21 | 13 passed, 0 failed |
| WebKit Desktop | 3 | pass | 2026-10-21 | 13 passed, 0 failed |
| WebKit Mobile (iPhone 14 emulation) | 2 | pass | 2026-10-21 | 13 passed, 0 failed |
On different devices
Reduced motion (static): Button retains static position without magnetic cursor tracking.
| Tier | What it does |
|---|---|
| T3 Full | Same behaviour as tier 2: spring physics on the shared frame loop while the pointer is over the wrapper, settling to zero frames |
| T2 Standard | Magnetic pull with the configured strength, only when the device reports (hover: hover) and (pointer: fine) |
| T1 Lite | Static wrapper without pointer handlers (coarse pointer with low-end hints) |
| T0 Static | Static wrapper without pointer handlers or translation (server render, prefers-reduced-motion, Save-Data, or no WebGL2) |
Content Security Policy
- Works without
'unsafe-eval'. - Needs no reveal gate.
- Sets inline
styleattributes, so allowstyle-src-attr 'unsafe-inline'.