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

or

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

1. Install dependencies:

   npm install

2. Start development server:

   npm run dev

3. Run tests:

   npm test

4. 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:

1. Create a test package:

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

2. Test in another project:

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

3. Verify the package works as expected in your test project

Publishing Steps

1. 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)

2. Build and publish:

   npm run build
   npm publish

3. Push changes and tags:

   git push && git push --tags

License

MIT © areknow