Skip to main content

​
Features

  • 🎯 Smooth physics-based cursor animations
  • 🔄 Rotation effects based on movement direction
  • ⚡ Performance optimized with RAF
  • 🎨 Fully customizable cursor design
  • 📦 Lightweight and easy to implement

​
Installation

    ​
    Usage

    showLineNumbers
    import { SmoothCursor } from "@/components/ui/smooth-cursor"
    showLineNumbers
    <SmoothCursor />

    ​
    Hiding Default Browser Cursor

    To prevent the default browser cursor from overlapping with the custom cursor, add the following CSS globally:
    showLineNumbers
    * {
  cursor: none !important;
}

    ​
    Optional: Keep text cursor for inputs

    showLineNumbers
    input,
textarea,
select {
  cursor: text !important;
}
    If you’re using Tailwind CSS, you can add cursor-none to your layout wrapper:
    showLineNumbers
    <div className="cursor-none">
  <SmoothCursor />
  {/* your app */}
</div>

    ​
    Props

    PropTypeDefaultDescription
    cursorReact.ReactNode<DefaultCursorSVG />Custom cursor component to replace the default cursor
    springConfigSpringConfigSee belowConfiguration object for the spring animation behavior

    ​
    SpringConfig Type

    showLineNumbers
    interface SpringConfig {
  damping: number // Controls how quickly the animation settles
  stiffness: number // Controls the spring stiffness
  mass: number // Controls the virtual mass of the animated object
  restDelta: number // Controls the threshold at which animation is considered complete
}

    ​
    Default Spring Configuration

    showLineNumbers
    const defaultSpringConfig = {
  damping: 45,
  stiffness: 400,
  mass: 1,
  restDelta: 0.001,
}

    ​
    Browser Support

    Compatible with all modern browsers that support:
    • requestAnimationFrame
    • CSS transforms
    • Pointer events

    ​
    Accessibility

    When using this component, consider that:
    • Users navigating via keyboard will not see the custom cursor
    • You may want to provide alternative visual cues for interactive elements
    • Some users may have motion sensitivity, so consider providing a way to disable the animation

    ​
    Credits

    • Credit to @Code_Parth for the original concept and implementation

    Build docs developers (and LLMs) love

    Get started for freeTalk to us