React Component Cursor


A flexible and customizable React component for creating smooth, interactive custom cursors and enhancements.

Features

- Use any React component
- Smooth cursor movement with configurable smoothing
- Global and Container-specific cursors
- Supports Multiple instances
- Lightweight (<10KB)
- Zero dependencies (except React)

Installation

``bash
npm install @yhattav/react-component-cursor
or
yarn add @yhattav/react-component-cursor
`

Note: If you wish to, You'll need to hide the native cursor with CSS (like cursor: none in the example above). See our styling guide for different approaches.

📖 New to the library? Check out our comprehensive Getting Started Guide for step-by-step tutorials and examples.

Basic Usage

`tsx
import { CustomCursor } from '@yhattav/react-component-cursor';

function App() {
return (
<>
{/ Hide native cursor globally /}



style={{
width: '20px',
height: '20px',
backgroundColor: '#3b82f6',
borderRadius: '50%',
}}
/>

{/ Your app content /}

);
}
`

📋 Complete API Reference

$3

The main component for creating custom cursors.

#### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| children | ReactNode | - | The React component/element to use as cursor content |
| enabled | boolean | true | Whether the cursor is enabled and visible |
| smoothness | number | 1 | Movement smoothing factor (1=instant, higher=smoother) |
| containerRef | RefObject | - | Limit cursor to specific container element |
| offset | CursorOffset | { x: 0, y: 0 } | Pixel offset from mouse position |
| centered | boolean | true | Auto-center cursor content on mouse position |
| throttleMs | number | 0 | Throttle mouse events in milliseconds |
| className | string | '' | Additional CSS classes for cursor container |
| style | CSSProperties | {} | Additional inline styles for cursor container |
| zIndex | number | 9999 | CSS z-index for cursor container |
| onMove | CursorMoveHandler | - | Callback fired on cursor movement |
| onVisibilityChange | CursorVisibilityHandler | - | Callback fired when cursor visibility changes |
| id | string | auto-generated | Unique identifier for cursor instance |
| showDevIndicator | boolean | true | [Dev Only] Show debug ring in development |
| data-testid | string | - | Test ID for automated testing |
| role | string | - | ARIA role for accessibility |
| aria-label | string | - | ARIA label for accessibility |

$3

The library is written in TypeScript and includes built-in type definitions.

`tsx
import type {
CustomCursorProps,
CursorPosition,
CursorOffset,
CursorMoveHandler,
CursorVisibilityHandler,
CursorVisibilityReason,
} from '@yhattav/react-component-cursor';
`

📖 Complete TypeScript Reference →

All prop types, interfaces, and future-ready types with usage examples.

$3

Optional utility functions for advanced SSR scenarios:

`tsx
import { isSSR, isBrowser, browserOnly, safeDocument, safeWindow } from '@yhattav/react-component-cursor';
`

📖 Complete SSR Guide →

$3

Optimized for performance with advanced control for complex use cases.

📖 Complete Performance Guide →

Optimization strategies, settings matrix, and advanced techniques.

$3

Works out of the box with Next.js, Gatsby, Remix, and other SSR frameworks.

`tsx
// Zero configuration needed - SSR handled automatically
import { CustomCursor } from '@yhattav/react-component-cursor';

Local Examples (clone and run):
`bash


Vite React example with multiple cursor demos

`tsx
function ContainerExample() {
const containerRef = useRef(null);
return (
ref={containerRef}
style={{
position: 'relative',
cursor: 'none', // Hide native cursor in this container
}}
>

style={{
width: '40px',
height: '40px',
border: '2px solid #ef4444',
borderRadius: '50%',
}}
/>

{/ Container content /}