React Use Cursor Follow

A lightweight React hook that creates a smooth, customizable animated cursor element that follows your mouse movement. Perfect for creating modern, interactive user experiences with custom cursor effects.

Documentation Guide

CodeSandbox Demo

Overview

React Use Cursor Follow provides a performant way to create custom cursor effects that smoothly follow mouse movement. The hook creates a floating element that trails behind your cursor with customizable easing, size, color, and behavior options.

Key Features

🎯 Smooth cursor following with customizable easing
🎨 Fully customizable appearance (color, size, shape)
⚡ Optimized performance with configurable update intervals
🌅 Smart fade effects near viewport edges
👁️ Optional default cursor hiding
🔧 TypeScript support with comprehensive type definitions
📱 Responsive and works across all screen sizes

Installation

npm install react-use-cursor-follow

yarn add react-use-cursor-follow

Quick Start

import { useCursorFollow } from "react-use-cursor-follow";

function App() {
  useCursorFollow({ color: "red" });

  return (
    <div>
      <h1>Move your mouse around!</h1>
      <p>You'll see a custom red cursor following your mouse.</p>
    </div>
  );
}

Hook API

Options

Option	Type	Default	Description
`easingFactor`	`number`	`0.1`	Easing factor for smooth movement (0.01-0.5)
`updateInterval`	`number`	`15`	Update interval in milliseconds (5-50)
`size`	`number`	`14`	Size of the cursor element in pixels (5-50)
`color`	`string`	`"#fff"`	Color of the cursor element
`borderRadius`	`string`	`"100%"`	Border radius for shape customization
`zIndex`	`number`	`9999`	Z-index for stacking order
`hideCursor`	`boolean`	`true`	Whether to hide the default browser cursor
`fadeDuration`	`number`	`200`	Fade transition duration in milliseconds
`fadeDistance`	`number`	`10`	Distance from edges where fading starts

Browser Support

The hook utilizes modern web APIs including:

requestAnimationFrame for smooth animations
CSS transitions for fade effects
Standard DOM event handling
CSS positioning and transforms

Ensure your target browsers support these features or include appropriate polyfills.

Development

Prerequisites

Node.js (version 16 or higher)
npm or yarn

Local Development

Install dependencies:
```
npm install
```
Start development server:
```
npm run dev
```
Run tests:
```
npm test
```
Build the package:
```
npm run build
```

Documentation

View the interactive documentation and examples:

npm run styleguide

Publishing Process

Before publishing a new version, ensure you complete the following checklist:

[ ] All tests pass (npm test)
[ ] Code is linted (npm run lint)
[ ] TypeScript compilation succeeds (npm run typecheck)
[ ] Documentation is up to date
[ ] Version number is appropriate for changes (following semver)
[ ] Git working directory is clean

Testing the Package Locally

Before publishing to npm, it's recommended to test the package locally:

Create a test package:

npm pack --dry-run  # List the files that will be included
npm pack           # Create the tarball

Test in another project:

cd ../your-test-project
npm install ../react-use-cursor-follow/react-use-cursor-follow-x.y.z.tgz

Verify the package works as expected in your test project

Publishing Steps

Update the version:

npm version patch  # for bug fixes (1.0.0 -> 1.0.1)
npm version minor  # for new features (1.0.0 -> 1.1.0)
npm version major  # for breaking changes (1.0.0 -> 2.0.0)

Build and publish:
```
npm run build
npm publish
```
Push changes and tags:
```
git push && git push --tags
```