XY-PX: Cursor Coordinates Tracker

A lightweight, cross-platform React component for tracking and displaying cursor/touch coordinates with real-time updates, platform-specific key bindings, and mobile support. Perfect for communicating precise positioning to LLMs like ChatGPT, Claude, and Copilot.

🚀 Live Demo | 📦 NPM Package | 💻 GitHub

🤖 Perfect for AI-Assisted Development

XY-PX bridges the gap between visual design and LLM communication. When working with AI assistants, you can now provide exact coordinates for precise element positioning:

• Tell your LLM: "Move the button to [245, 380]" → Get exact CSS positioning
• Say: "Place the modal at coordinates X: 450, Y: 200" → Receive precise transform values
• Request: "Center the element at [960, 540]" → Get perfect centering code
• Copy coordinates with Alt+Click and paste directly into your AI prompt

This tool transforms vague positioning requests into precise, pixel-perfect implementations when working with AI coding assistants.

✨ Features

• 🎯 Real-time Tracking - Display viewport and page coordinates as you move
• 🖱️ Multi-platform Support - Automatic OS detection (Mac, Windows, Linux, iOS, Android)
• ⌨️ Smart Key Bindings - Platform-specific modifier keys (⌥ Option for Mac, Alt for Windows)
• 📱 Touch Support - Full mobile support with long-press detection
• 🎨 Customizable Themes - Light, dark, and auto theme options
• 📋 Click to Copy - Instant coordinate copying to clipboard
• 🔄 Platform Toggle - Manual OS switching with visual indicators
• 💾 Persistent Preferences - Saves user settings in localStorage
• 🎭 Minimal UI - Clean, unobtrusive heads-up display

📦 Installation

npm install xy-px
# or
yarn add xy-px
# or
pnpm add xy-px

🚀 Quick Start

import React from 'react';
import { CursorCoordinates } from 'xy-px';
import 'xy-px/dist/index.css';

function App() {
  return (
    <div>
      <CursorCoordinates />
      {/* Your app content */}
    </div>
  );
}

🔧 Configuration

Basic Usage with Options

<CursorCoordinates
  position="top-right"
  theme="dark"
  opacity={0.4}
  showPlatformToggle={true}
/>

Advanced Configuration

<CursorCoordinates
  // Display options
  showByDefault={true}
  position="top-right"
  opacity={0.4}
  
  // Platform settings
  platform="auto" // 'auto' | 'mac' | 'windows' | 'ios' | 'android' | 'linux'
  showPlatformToggle={true}
  
  // Feature toggles
  showViewportCoords={true}
  showPageCoords={true}
  showScrollPosition={true}
  enableAltTracking={true}
  enableCopyOnClick={true}
  enableTouchTracking={true}
  
  // Touch settings
  longPressDelay={500} // milliseconds
  
  // Keyboard shortcuts
  toggleShortcut="Ctrl+Shift+C" // Custom shortcut
  
  // Styling
  theme="auto" // 'dark' | 'light' | 'auto'
  customClassName="my-custom-class"
  
  // Callbacks
  onCopy={(text) => console.log('Copied:', text)}
  onToggle={(visible) => console.log('Visible:', visible)}
  onPlatformChange={(platform) => console.log('Platform:', platform)}
/>

📖 API Reference

Props

⌨️ Keyboard Shortcuts

Default Shortcuts by Platform

🎨 Theming

Using Built-in Themes

// Dark theme
<CursorCoordinates theme="dark" />

// Light theme
<CursorCoordinates theme="light" />

// Auto (follows system preference)
<CursorCoordinates theme="auto" />

Custom Styling

/* Override default styles */
.my-custom-class {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  border-radius: 16px;
}

.my-custom-class .coord-value {
  color: #ffd700;
}

📱 Mobile Support

The component automatically detects mobile devices and adjusts interactions:

• iOS/Android: Long press to show coordinates, tap to copy
• Touch-optimized: Larger touch targets and adjusted positioning
• Responsive: Adapts to different screen sizes

🔄 Platform Detection

The component automatically detects the user's platform and adjusts key bindings accordingly. Users can also manually switch platforms using the toggle button:

• 🍎 macOS
• 🪟 Windows
• 🐧 Linux
• 📱 iOS
• 🤖 Android

💡 Examples

Working with AI/LLM Assistants

<CursorCoordinates 
  enableCopyOnClick={true}
  position="top-right"
/>

Workflow:

1. Hold Alt/Option to see cursor-following display
2. Alt+Click to copy coordinates
3. Paste into your AI prompt: "Move the header to [425, 120]"
4. Get precise positioning code from your LLM

Example AI Prompts:

• "Position the button at exactly [300, 450]"
• "Create a tooltip that appears at coordinates X: 523, Y: 201"
• "Align these three elements at Y: 350 with X coordinates [100, 300, 500]"
• "Draw a line from [50, 100] to [450, 300]"

Minimal Setup

import { CursorCoordinates } from 'xy-px';
import 'xy-px/dist/index.css';

<CursorCoordinates />

Custom Position and Theme

<CursorCoordinates 
  position="bottom-left"
  theme="light"
  opacity={0.6}
/>

Development Tool Configuration

<CursorCoordinates
  showByDefault={process.env.NODE_ENV === 'development'}
  position="bottom-right"
  enableCopyOnClick={true}
  onCopy={(coords) => {
    console.log('Debugging coordinates:', coords);
  }}
/>

Mobile-First Configuration

<CursorCoordinates
  platform="auto"
  enableTouchTracking={true}
  longPressDelay={300}
  position="top-left"
/>

🛠️ Development

Setup

# Clone the repository
git clone https://github.com/AltivumInc-Admin/xy-px.git
cd xy-px

# Install dependencies
npm install

# Start development server
npm run dev

# Run demo
npm run demo

Scripts

• npm run build - Build the library
• npm run dev - Watch mode for development
• npm run demo - Run demo application
• npm run lint - Run ESLint
• npm run typecheck - Run TypeScript type checking

Project Structure

xy-px/
├── src/
│   ├── CursorCoordinates.tsx    # Main component
│   ├── CursorCoordinates.css    # Component styles
│   ├── utils/
│   │   └── platform.ts          # Platform detection utilities
│   └── index.ts                 # Package entry
├── demo/                         # Demo application
├── dist/                         # Build output
└── package.json

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with React and TypeScript
• Bundled with Rollup
• Styled with modern CSS

📮 Support

For issues and feature requests, please create an issue.

Made with ❤️ by Altivum Inc