The default browser cursor is boring. Three lines, one shade of grey, 0 personality. A custom cursor — especially one that follows your mouse, snaps magnetically to buttons, and pulses on hover — signals "this is a designed experience, not a template drop-in". But custom cursors also tank UX when they're slower than your actual pointer, when they hide on drag, or when they obscure text. The line between premium and gimmicky is thin. Velocity X uses the mouse-follower library to ship subtle custom cursors on hero + portfolio sections without breaking form pages or dashboards. This is how we separate the wins from the gotchas.
When Custom Cursors Actually Help
Custom cursors work when they strengthen the brand story or guide user attention. A portfolio site is a **portfolio experience** — the cursor is part of the stage design, not a utility. A CRM dashboard is a **task tool** — the cursor is invisible scaffolding. Design-engineering portfolios, agency homepages, premium SaaS landing pages, and interactive showcases gain dwell time and perceived polish from a custom cursor. Form pages, dashboards, and content-heavy sites lose friction by **not** having one.
The sweet spot: magnetic snap to CTAs (buttons feel magnetic, cursor jumps ±8px when hovering), a subtle animated ring or dot that trails 80–120ms behind your actual pointer, and a secondary "grab" state when hovering over draggable elements. The cursor never obscures text or form inputs. On touch devices, it vanishes entirely — no custom cursor is needed because there's no mouse. On prefers-reduced-motion, the trailing animation disables but the snap target remains active.
Architecture: mouse-follower Library + Data Attributes
We use mouse-follower (npm, 16KB minified) to drive the custom cursor on the client. It exposes a global mouseCursor object: register followers (the animated ring), set cursor state (text, grab, pointer), and bind targets for magnetic snapping. The library does all the math — tracking pointer position, easing the follower behind, and snapping on proximity. You just set it up once and drop data attributes on the DOM.
{`import MouseFollower from 'mouse-follower';
import 'mouse-follower/dist/mouse-follower.min.css';
// Initialize once in Layout.astro or a Astro island
const cursor = new MouseFollower({
speed: 0.15, // 0.1–0.3; lower = slower trail, more visible lag
visibleRadius: 8, // inner dot size
textColor: '#a78bfa', // purple to match brand
});
// Optional: register all [data-cursor="snap"] elements
document.querySelectorAll('[data-cursor="snap"]').forEach((el) => {
cursor.registerTarget(el);
});`}Then, in your Astro components, add the data attribute to CTAs and interactive elements:
{`
View Pricing
`}The library does the rest. When your pointer enters a [data-cursor="snap"] element, the cursor ring snaps to the button's centre. When you press down, the cursor state changes to grab. When you hover text, the cursor becomes a text caret. No JavaScript on your end.
Touch Device Disable & Prefers-Reduced-Motion
Custom cursors are invisible on touch. A phone doesn't have a mouse, so detecting (pointer: coarse) in CSS or navigator.maxTouchPoints > 0 in JS, we skip cursor init entirely. Save 16KB. No footgun of a hidden cursor on mobile.
{`// In your cursor init script
const isTouchDevice = () =>
navigator.maxTouchPoints > 0 ||
navigator.msMaxTouchPoints > 0 ||
window.matchMedia('(pointer: coarse)').matches;
if (!isTouchDevice()) {
const cursor = new MouseFollower({ speed: 0.15 });
}`}For prefers-reduced-motion: reduce, disable the trailing animation but keep the snap targets active. Some users have motion sensitivity; the magnetic snap is functional, not disorienting.
{`const prefersReducedMotion = window.matchMedia(
'(prefers-reduced-motion: reduce)'
).matches;
const cursor = new MouseFollower({
speed: prefersReducedMotion ? 0.01 : 0.15, // instant vs slow trail
visibleRadius: prefersReducedMotion ? 4 : 8,
});`}Real Aidxn Examples
Velocity X enables custom cursors on the hero section (fullscreen slider with Hormozi headlines — CTAs snap magnetically), the portfolio/radial gallery (draggable wheel of work samples), and the pricing cards (each tier links to a detail page). Dashboard pages, blog content, and internal tools disable it. The cursor disappears when you scroll off the hero, reappears when you scroll back. No tracking overhead outside the zones where it adds value.
The visual is a 12px purple ring with a 3px inner dot, trailing 0.15 speed (80–120ms lag on a typical mouse). When you enter a CTA button, the ring snaps within 6px of the button's centre. On drag, it becomes a 16px circle with a "grab" icon overlay. The whole effect is 2KB of CSS + 16KB library (gzipped ~6KB).
Frequently Asked Questions
What if the custom cursor lags behind the pointer?
Increase the speed value (0.3+ = faster, less visible lag). Test on your target device; desktop handles 0.2–0.25 cleanly, mobile might need 0.1–0.15 if there's jank. If lag persists, check for JS blocking the main thread — debounce resize handlers, defer non-critical timers, and profile in DevTools.
Can I animate the cursor (colour change, size pulse)?
Yes. The library gives you hooks to listen to state changes. Add a CSS class to the cursor ring on pointerdown or when entering a snap target, then animate via CSS transitions. Keep animations under 200ms — longer and the lag becomes noticeable.
Does mouse-follower work in React components?
Yes. Initialize once in the root layout, not per-component. Use useEffect with an empty dependency array so init fires once. Register snap targets via a separate effect that watches the DOM.
What about keyboard navigation? Will the cursor block focus outlines?
No. The cursor is absolutely positioned and pointer-events: none, so it never interferes with focus states. Tab through a button and the cursor ring sits behind the native focus outline. Both visible together, no collision.
Can I use a custom image instead of the ring?
Yes. Mouse-follower lets you replace the follower with your own SVG or image. Craft a 64px × 64px PNG (or SVG) with transparency, pass it to the config, and it follows your mouse. Keep it minimal — busy cursors distract from content.
How do I disable the cursor for specific pages?
Add a class to the root layout (e.g., data-no-cursor) and check it in your init. Or use a Zustand store to toggle cursor state per route. Simple toggle: check if the current pathname includes "dashboard" or "forms", and skip init.
The Bottom Line
Custom cursors elevate design-engineering portfolios, agency sites, and premium experiences — but they torpedo dashboards, forms, and content-heavy pages. The secret is **constraint**: custom cursor only on hero + portfolio sections, disabled on touch + reduced-motion, magnetic snap on CTAs, keyboard-safe with focus outlines visible. Mouse-follower gives you the library; you provide the discipline. Slap data attributes on your buttons, initialize once, and let the UX breathe. Your portfolio just got a glow-up.