Circle Cursor
A single solid orange follower circle with smooth requestAnimationFrame inertia, viewport-wide tracking, automatic touch-device disablement, and light/dark theme support.
Installation#
pnpm dlx shadcn@latest add @davinciui/circle-cursorUsage#
API Reference#
| Prop | Type | Default |
|---|---|---|
sizeDiameter of the circle in pixels. | number | 46 |
colorSolid fill color used for both themes unless overridden by lightColor / darkColor. | string | "#FF3B0A" |
lightColorFill color used on light backgrounds. | string | "#EA580C" |
darkColorFill color used on dark backgrounds. | string | "#FF3B0A" |
themeColor scheme. "auto" follows the site theme live. | "auto" | "light" | "dark" | "auto" |
followSpeedInterpolation per frame from 0.12 (soft) to 0.22 (tight). | number | 0.16 |
hideNativeCursorHide the browser cursor on fine-pointer devices while active. | 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 element. | string | — |
Accessibility#
It is a decorative aria-hidden, pointer-events-none div that never receives focus. The effect runs only on fine pointers and disables itself for coarse pointers or reduced motion, restoring the native cursor.
Motion#
A requestAnimationFrame loop interpolates position using followSpeed, while opacity and color transition over 120ms and 200ms. prefers-reduced-motion is watched live and disables the follower, restoring the native cursor.
Known constraints#
- Mouse-only: the effect never runs on touch or other coarse pointers.
- Reduced motion disables the follow animation and leaves the native cursor in place.
- The overlay is decorative, so interactive elements still need their own visible affordances.
View source
Keep in mind
Need a custom component?
I build bespoke UI components & websites tailored to your brand.

