AnimatedPrecisionCursor

A high-precision animated cursor with crosshair guides and live coordinate display. Perfect for creative tools, interactive portfolios, and interfaces requiring enhanced pointer feedback and accuracy.

✨ Features

Smooth Motion: Spring-based animation with customizable physics
Crosshair Guides: Dynamic crosshair overlays that appear on interactive elements
Live Coordinates: Real-time X/Y position display
Smart Detection: Automatically detects interactive elements (buttons, links, inputs)
Dark Mode: Built-in support for light and dark themes
Performance Optimized: Uses requestAnimationFrame throttling
Accessible: Includes ARIA labels and live regions

📋 Prerequisites

This component requires:

Next.js (with App Router)
Tailwind CSS 4

🚀 Installation

npm install motion

📁 Files Included

The component bundle includes:

index.tsx - Main component
context.tsx - Cursor context provider
README.md - This documentation

🎯 Basic Usage

tsx.tsxTypeScript

1import { CursorProvider } from './components/cursor/context';
2import { AnimatedPrecisionCursor } from './components/cursor';
3
4export default function App() {
5    return (
6        <CursorProvider>
7            <div className="min-h-screen">
8                <AnimatedPrecisionCursor />
9
10                {/* Your page content */}
11                <button className="px-4 py-2 bg-blue-500 text-white rounded">
12                    Interactive Button
13                </button>
14            </div>
15        </CursorProvider>
16    );
17}

🔧 Props

AnimatedPrecisionCursor

Prop	Type	Default	Description
`className`	`string`	`""`	Additional CSS classes for the cursor wrapper
`springConfig`	`object`	`{ stiffness: 250, damping: 45 }`	Motion spring configuration

SpringConfig Object

Property	Type	Default	Description
`stiffness`	`number`	`250`	Spring stiffness (higher = snappier)
`damping`	`number`	`45`	Spring damping (higher = less bouncy)

🎨 Cursor Context

Use the useCursor hook to control the cursor from any component:

tsx.tsxTypeScript

1import { useCursor } from './components/cursor/context';
2
3function InteractiveElement() {
4    const { setLabel, setScale } = useCursor();
5
6    return (
7        <button
8            onMouseEnter={() => {
9                setLabel('Click to explore');
10                setScale(1.2);
11            }}
12            onMouseLeave={() => {
13                setLabel('');
14                setScale(1);
15            }}
16        >
17            Hover me
18        </button>
19    );
20}

📖 Examples

Basic Implementation

tsx.tsxTypeScript

1import { CursorProvider } from './components/cursor/context';
2import { AnimatedPrecisionCursor } from './components/cursor';
3
4function MyApp() {
5    return (
6        <CursorProvider>
7            <AnimatedPrecisionCursor />
8            <main>
9                <h1>My Portfolio</h1>
10                <button>Contact Me</button>
11            </main>
12        </CursorProvider>
13    );
14}

Custom Spring Configuration

tsx.tsxTypeScript

1<AnimatedPrecisionCursor
2    springConfig={{
3        stiffness: 400,
4        damping: 30,
5    }}
6/>

Interactive Elements with Labels

tsx.tsxTypeScript

1function Portfolio() {
2    const { setLabel } = useCursor();
3
4    return (
5        <div className="grid grid-cols-2 gap-4">
6            <div
7                className="p-8 border rounded-lg cursor-pointer"
8                onMouseEnter={() => setLabel('View Project')}
9                onMouseLeave={() => setLabel('')}
10            >
11                Project 1
12            </div>
13
14            <div
15                className="p-8 border rounded-lg cursor-pointer"
16                onMouseEnter={() => setLabel('Coming Soon')}
17                onMouseLeave={() => setLabel('')}
18            >
19                Project 2
20            </div>
21        </div>
22    );
23}

Scaling Effect

tsx.tsxTypeScript

1function ScalingButton() {
2    const { setScale } = useCursor();
3
4    return (
5        <button
6            className="px-6 py-3 bg-gradient-to-r from-purple-500 to-pink-500 text-white rounded-lg"
7            onMouseEnter={() => setScale(1.5)}
8            onMouseLeave={() => setScale(1)}
9        >
10            Hover for scale effect
11        </button>
12    );
13}

🎭 Automatic Behaviors

The cursor automatically detects and responds to:

Buttons (<button> elements)
Links (<a> elements)
Form inputs (<input>, <select>, <textarea>)
Elements with cursor-pointer class
Elements with role="button"
Elements with onclick handlers
Focusable elements (with tabindex)

When hovering over these elements:

Crosshair guides appear
Live coordinates are displayed
Cursor slightly scales down (0.9x)

🔧 Requirements

The cursor only works on client-side (uses "use client")
Requires mouse/pointer input
Best experienced on desktop/laptop devices

💡 Tips

Wrap your entire app with CursorProvider for global cursor control
Use sparingly - Only add labels/scaling to important interactive elements
Test on different screens - Coordinates and crosshairs adapt to viewport size
Consider mobile - The cursor gracefully handles touch devices by not rendering