v1.2.1

@hwagfu/cursor

Animated cursor effect: a spring-following ring, center dot and pastel particle trail.

A React component that adds a smooth cursor effect with a spring-following ring, a center dot and a pastel particle trail. Deeply customizable via props, hides itself on mobile and never blocks clicks.

Playground

Tweak the controls on the right to see the component update live.

Bật công tắc “enabled” để kích hoạt hiệu ứng con trỏ · Turn on “enabled” to activate.

enabled

ringSize42pxringHoverSize65pxdotSize10pxparticleLifetime900ms

ringColor

dotColor

particleColor

Installation

bash

npm install @hwagfu/cursor motion

tsx

import { CursorEffect } from "@hwagfu/cursor";

Features

A spring-following ring with a center dot.
A pastel particle trail with customizable colors, count and lifetime.
Automatically hides on touch / mobile devices.
Uses position: fixed + pointer-events: none so it never blocks clicks.
Quick install via the shadcn registry.

Usage

Basic usage

tsx

import { CursorEffect } from "@hwagfu/cursor";

export default function App() {
  return (
    <>
      <CursorEffect />
      <main>Your app</main>
    </>
  );
}

Customization

tsx

<CursorEffect
  colors={["#fda4af", "#fdba74", "#86efac", "#93c5fd"]}
  particleLifetime={900}
  maxParticles={24}
  ringSize={36}
  ringHoverSize={56}
  ringColor="#cbd5e1"
  ringHoverColor="#0f172a"
  dotColor="#0f172a"
  interactiveSelector="a, button, [data-cursor]"
/>

Install via shadcn

bash

# Từ GitHub repo công khai có registry.json ở gốc
npx shadcn@latest add <owner>/<repo>/cursor

import { CursorEffect } from "@/components/ui/cursor";

Props

Name	Type	Default	Description
colors	string[]	pastel palette	Colors used by the particle trail.
particleLifetime	number	1000	Particle lifetime in milliseconds.
particleSpawnChance	number	0.6	Chance to spawn a particle on each mouse move (0–1).
maxParticles	number	40	Maximum visible particles kept at once.
particleSize	number	8	Particle size in pixels.
ringSize	number	42	Default outer ring size in pixels.
ringHoverSize	number	65	Outer ring size while hovering interactive elements.
dotSize	number	10	Center dot size in pixels.
ringColor	string	"#D3D3D3"	Default outer ring border color.
ringGlow	string	"none"	CSS box-shadow used to glow the ring.
ringHoverColor	string	"#000000"	Outer ring border color on hover.
dotColor	string	"rgba(75,85,99,0.6)"	Center dot color.
zIndex	number	99999	Stacking order for the cursor effect.
interactiveSelector	string	"a,button,[role=button],..."	Elements matching this selector trigger the hover state.

Notes

The component automatically returns null on touch / mobile devices.
The UI uses position: fixed and pointer-events: none, so it won't block clicks.