Custom Cursor Systems

When to use this

• Building a portfolio, agency, or editorial site where a custom cursor is a deliberate design choice.
• Implementing contextual cursor states: "View" on project cards, "Drag" on sliders, "Play" on video thumbnails.
• Creating a blend-mode-difference cursor that inverts over light and dark backgrounds.
• Adding a trailing dot/ring follower with lerp delay for a fluid feel.
• Do NOT use this for magnetic pull-toward-button effects; see magnetic-cursor-interactions instead.

Mental model

A custom cursor is a DOM element positioned with transform: translate() on every mousemove. The native cursor is hidden with cursor: none on the body. The custom cursor follows the real one with a lerp delay that gives it a trailing, fluid feel.

The cursor has a state machine. States are things like default, hover, drag, text, view, hidden. Each state maps to a size, color, blend mode, opacity, and optional text label. State transitions are triggered by mouseenter/mouseleave on elements with data-cursor attributes.

The critical detail: the custom cursor element must have pointer-events: none or it will intercept clicks meant for elements underneath it. This is the number-one bug.

Performance-wise, the cursor element should be a promoted compositor layer (will-change: transform). All styling changes happen via class toggling, not inline style manipulation per-frame.