cursor-style

Started as a personal need for a custom cursor. Now it features six unique types, extensive customization options, and maintains smooth 60 FPS performance at only 16 KB.

What's New in v1.5.1

• Optimized default values for all cursor types
• Better models straight out of the box

Installation

npm install cursor-style

Quick Start

import { CustomCursor } from "cursor-style";

function App() {
  return (
    <div>
      <CustomCursor type="one" size={35} bgColor="white" clickEffect="pulse" />
      {/* Your content here */}
    </div>
  );
}

Available Cursor Types

The library includes six different cursor types:

| Type | Description | |------|-------------| | one | Simple filled circle - clean and customizable | | two | Dot with outline ring - two parts you can style independently | | three | Outline-only circle with transparent center | | four | Crosshair with rotation, tilt, and transform effects | | five | Image hover system with dynamic positioning | | six | Morphing cursor that adapts to element shapes |

Usage Examples

Basic Cursor

<CustomCursor type="one" size={35} bgColor="white" />

Dot + Outline

<CustomCursor type="two" sizeDot={10} sizeOutline={45} delay={15} />

Image Hover

<CustomCursor type="five" showImages imageSize={30} imageFollowDelay={20} />
<span data-cursor-image="/path/to/image.jpg">Hover me</span>

Morphing Cursor

<CustomCursor type="six" baseSize={2} morphDuration={25} />

Features

Click effects, magnetic attraction, image previews, mix blend modes, full TypeScript support with discriminated unions. See full documentation for API reference, advanced techniques, and performance optimization.

Common Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | type | "one" | "two" | "three" | "four" | "five" | "six" | Required | Cursor variant | | size | 0-100 | 35 | Base size (×10 internally) | | delay | 0-50 | 0 | Movement delay (ms) | | scaleOnHover | -10 to 10 | 0 | Scale on hover | | clickEffect | "pulse" | "ripple" | "fade" | - | Click animation | | clickEffectColor | string | "white" | Click effect color | | clickEffectSize | 0-100 | 1.5 | Click effect size | | clickEffectDuration | 0-100 | 30 | Click duration (ms) | | magnetEffect | boolean | false | Magnetic attraction | | magnetStrength | 0-50 | 2 | Magnet strength | | magnetRange | 0-50 | 10 | Magnet range (px) | | magnetClassName | string | "cursor-magnet" | Target class | | magnetType | "attract" | "repel" | "attract" | Magnet behavior | | useMixBlendDifference | boolean | true | Blend mode | | overrideOpacity | 0-1 | - | Custom opacity |

Each cursor type has specific props. See documentation for complete API reference.

Documentation • GitHub • NPM

MIT © nsl-nikos