Magic Cursor Pro
A compact outlined cursor with natural spring weight, subtle click compression, dynamic blend support, and automatic touch/portrait disablement.
Installation#
pnpm dlx shadcn@latest add @davinciui/magic-cursor-proUsage#
API Reference#
| Prop | Type | Default |
|---|---|---|
customIconPNG, SVG, or data URL used instead of the default arrow. | string | — |
invertDefaultIconSwap the default arrow fill and outline. | boolean | false |
iconSizeCursor icon width and height in pixels. | number | 34 |
themeDefault arrow colors. Auto follows the site theme live. | "auto" | "light" | "dark" | "auto" |
mixBlendModeUse difference or exclusion for dynamic background contrast. | CSS mix-blend-mode | "normal" |
clickSquishCompress and rebound the icon on primary clicks. | boolean | true |
stiffnessSpring pull toward the pointer. | number | 400 |
dampingSpring resistance; higher is tighter. | number | 35 |
massCursor weight and trailing behavior. | number | 1 |
hideSystemCursorHide the browser cursor while the effect is active. | boolean | true |
disableOnPortraitDisable on portrait screens in addition to touch devices. | boolean | true |
zIndexOverlay stacking order. | number | 9999 |
disabledDisable without unmounting. | boolean | false |
disableManualInputIgnore real pointer input; follow only synthetic/programmatic movement (self-playing previews). | boolean | false |
containerRefOptionally constrain pointer tracking and rendering to a positioned host. | RefObject<HTMLElement> | — |
classNameClasses for the cursor wrapper. | string | — |
Accessibility#
The cursor overlay is aria-hidden and pointer-events none, so it adds no semantics. It disables itself on coarse pointers and prefers-reduced-motion, but hiding the system cursor can still disorient users; the effect has no keyboard interaction.
Motion#
A spring loop follows the pointer, controlled by stiffness, damping, and mass, while clickSquish adds a 130ms cubic-bezier icon compression. prefers-reduced-motion disables the effect entirely, restores the system cursor, and removes click feedback.
Known constraints#
- Hidden by default on coarse pointers and portrait layouts, so mobile users get the native cursor.
- Reduced motion keeps the effect from animating even when the pointer is fine.
- The effect is an overlay; links and buttons still need their own hover and focus states.
View source
Keep in mind
Need a custom component?
I build bespoke UI components & websites tailored to your brand.

