hwagfu-cursor

Animated React cursor effect with a spring-following ring, center dot, and pastel particle trail. Hieu ung con tro React duoc animate voi vong tron theo chuot, cham o giua, va vet hat pastel.

Install

npm install hwagfu-cursor motion

shadcn Registry

Use one of these install flows: Chon mot trong hai cach cai dat sau:

# Works immediately after this repo is pushed publicly with registry.json
npx shadcn@latest add <owner>/<repo>/cursor

# Works after @hwagfu is submitted to the shadcn registry directory
npx shadcn@latest add @hwagfu/cursor

This repository now includes: Repo nay da bao gom:

• registry.json: root shadcn registry catalog.
• cursor.json: flat registry item for the cursor component.
• registry/cursor.tsx: installable source file that the CLI copies into the consumer project.

Important: Luu y:

• owner/repo/cursor works with a public GitHub repository that contains registry.json at the root.
• @hwagfu/cursor only works after the @hwagfu namespace is added to the official shadcn registry directory.

Usage

import { CursorEffect } from "hwagfu-cursor";

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

Editor tooltip support is included through TypeScript JSDoc. When you hover CursorEffect or any prop in VS Code and similar editors, you'll see usage notes and what each prop controls. Ho tro tooltip trong editor duoc cung cap bang TypeScript JSDoc. Khi hover vao CursorEffect hoac tung prop trong VS Code va cac editor tuong tu, ban se thay mo ta cach dung va chuc nang cua tung prop.

Customization

import { CursorEffect } from "hwagfu-cursor";

export default function App() {
  return (
    <>
      <CursorEffect
        colors={["#fda4af", "#fdba74", "#86efac", "#93c5fd"]}
        particleLifetime={900}
        particleSpawnChance={0.35}
        maxParticles={24}
        ringSize={36}
        ringHoverSize={56}
        dotSize={8}
        ringColor="#cbd5e1"
        ringHoverColor="#0f172a"
        ringBackground="rgba(255,255,255,0)"
        ringHoverBackground="rgba(15,23,42,0.08)"
        dotColor="#0f172a"
        interactiveSelector="a, button, [data-cursor]"
      />
      <main>Your app</main>
    </>
  );
}

Build

npm install
npm run build

Registry Files

The shadcn registry item installs the component to: Registry item cua shadcn se cai component vao:

@ui/cursor.tsx

It also installs: Dong thoi se cai:

• motion

After adding with shadcn, import it like this: Sau khi add bang shadcn, import nhu sau:

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

Props

CursorEffect supports these optional props: CursorEffect ho tro cac prop tuy chon sau:

| Prop | Type | Default | Description / Mo ta | | --- | --- | --- | --- | | colors | string[] | pastel palette | Colors used by the particle trail. Mau dung cho vet hat theo sau con tro. | | particleLifetime | number | 1000 | Particle lifetime in milliseconds. Thoi gian ton tai cua moi hat, tinh bang mili giay. | | particleSpawnChance | number | 0.6 | Chance to spawn a particle on each mouse move, from 0 to 1. Xac suat tao them hat moi khi di chuot, tu 0 den 1. | | maxParticles | number | 40 | Maximum visible particles kept at once. So hat toi da duoc giu va hien thi cung luc. | | ringSize | number | 42 | Default outer ring size in pixels. Kich thuoc mac dinh cua vong tron ben ngoai. | | ringHoverSize | number | 65 | Outer ring size while hovering interactive elements. Kich thuoc vong tron khi hover vao phan tu tuong tac. | | dotSize | number | 10 | Center dot size in pixels. Kich thuoc cham o giua con tro. | | ringColor | string | "#D3D3D3" | Default outer ring border color. Mau vien mac dinh cua vong tron. | | ringHoverColor | string | "#000000" | Outer ring border color on hover. Mau vien cua vong tron khi hover. | | ringBackground | string | "rgba(0, 0, 0, 0)" | Default outer ring background. Mau nen mac dinh cua vong tron. | | ringHoverBackground | string | "rgba(0, 0, 0, 0.1)" | Outer ring background on hover. Mau nen cua vong tron khi hover. | | dotColor | string | "rgba(75, 85, 99, 0.6)" | Center dot color. Mau cua cham o giua con tro. | | zIndex | number | 99999 | Stacking order for the cursor effect. Thu tu xep lop cua effect con tro. | | interactiveSelector | string | "a,button,[role='button'],input,textarea,select,[data-cursor]" | Elements matching this selector trigger the hover state. Cac phan tu match selector nay se kich hoat trang thai hover. |

Notes

• The component automatically returns null on touch/mobile devices. Component se tu dong return null tren thiet bi mobile/cam ung.
• The cursor UI uses position: fixed and pointer-events: none, so it won't block clicks. Giao dien con tro dung position: fixed va pointer-events: none, nen se khong chan thao tac click.