@ayo0la/cursor

Self-injecting custom cursor with smooth lerp tracking, hover and click states. Zero dependencies.

Install

npm i @ayo0la/cursor

Usage

import { createCursor } from '@ayo0la/cursor'

const cursor = createCursor({
  color: '#ffffff',
  hoverScale: 5,
  easing: 0.12,
})

// later, if needed:
cursor.destroy()

SSR safe: Returns a no-op stub when typeof window === 'undefined'. Safe to import in Next.js, Nuxt, or SvelteKit without guards.

Options

| Option | Type | Default | Notes | |---|---|---|---| | size | number | 8 | Resting dot diameter in px | | hoverScale | number | 5 | Multiplied against size on hover. Used only if hoverSize is not set. | | hoverSize | number | — | Absolute hover diameter in px. Wins over hoverScale if both are set. | | color | string | '#ffffff' | Resting fill color | | hoverColor | string | same as color | Fill color on hover | | clickScale | number | 0.8 | Scale factor on mousedown; resets after 100ms | | clickColor | string | same as color | Fill color flash on mousedown | | easing | number | 0.12 | Lerp factor: 0.05 = smooth/laggy · 0.2 = snappy · 1 = instant | | blendMode | string | 'normal' | CSS mix-blend-mode. Note: 'difference' inverts colors under the cursor — looks great on dark backgrounds, breaks on light ones. | | hoverTargets | string | 'a, button, [role="button"]' | CSS selector for elements that trigger hover state | | zIndex | number | 9999 | Stack order of the injected element |

License

MIT