Aura Cursor

A lightweight, customizable library for creating custom cursors in modern web applications. Create beautiful cursors that follow your mouse with smooth animations and interactive hover effects. Try the controls on the side to see different configurations in real-time.

ReactTypeScriptNext.js

View on GitHub View on NPM

Customizable

Control size, color, opacity, speed, lag, shape and much more through simple props. Full TypeScript support.

Performance

Optimized for performance with smooth animations using requestAnimationFrame. Small bundle size and zero dependencies.

Smart Detection

Automatically detects interactive elements (links, buttons, etc.) and applies special hover effects. Automatically hides when the mouse leaves the window.

Flexible

Trail, magnetic snap, click pulse, outline mode, interactive-only and custom shapes. Works with React, HTML/JavaScript and TypeScript.

Installation

npm install aura-cursor

Or using yarn:

yarn add aura-cursor

Or using pnpm:

pnpm add aura-cursor

How to Use

Basic example with React:

import { AuraCursor } from "aura-cursor/react";

function App() {
  return (
    <>
      <AuraCursor
        size={30}
        color="#3b82f6"
        opacity={0.5}
        speed={0.2}
        lag={1.4}
        easing="easeOut"
        hideDefaultCursor
        shape="rounded"
        hoverColor="#3c096c"
        trail={{ length: 6, fade: 0.55, scale: 0.92 }}
        clickEffect={{ scale: 0.7, duration: 160 }}
        magnetic={{ strength: 0.4, padding: 48 }}
        hoverEffect={{
          scale: 1.8,
          color: "#3c096c",
          opacity: 0.5,
        }}
      />
      <YourApp />
    </>
  );
}

Or using the hook:

import { useAuraCursor } from "aura-cursor/react";

function App() {
  useAuraCursor({
    size: 30,
    color: "#3b82f6",
    opacity: 0.5,
    speed: 0.2,
    trail: { length: 4 },
    clickEffect: true,
  });

  return <div>Your app content</div>;
}

Or using vanilla JavaScript:

import { AuraCursor } from "aura-cursor";

const cursor = new AuraCursor({
  size: 30,
  color: "#3b82f6",
  opacity: 0.5,
  speed: 0.2,
  lag: 1.8,
  easing: "easeOut",
  hideDefaultCursor: true,
  shape: "rounded",
  hoverColor: "#3c096c",
  trail: { length: 6, fade: 0.55, scale: 0.92 },
  clickEffect: { scale: 0.7, duration: 160 },
  magnetic: { strength: 0.4, padding: 48 },
  hoverEffect: {
    scale: 1.8,
    color: "#3c096c",
    opacity: 0.5,
  },
});

cursor.init();

API Reference

All available props to customize Aura Cursor:

Prop	Type	Default	Description
`size`	number	`20`	Cursor size in pixels
`color`	string	`"#000000"`	Main cursor color (hex, rgb, etc)
`opacity`	number	`0.5`	Cursor opacity (0-1)
`speed`	number	`0.3`	Mouse follow speed (0-1)
`lag`	number	`1`	Delay multiplier (higher = more lag)
`easing`	string	`"linear"`	Interpolation easing toward the target (linear \| easeOut)
`hideDefaultCursor`	boolean	`false`	Hide browser default cursor
`interactiveOnly`	boolean	`false`	Show cursor only on interactive elements
`outlineMode`	boolean	`false`	Enable outline mode (outline only)
`outlineWidth`	number	`2`	Outline width in pixels
`centerDotColor`	string	`-`	Center dot color
`centerDotSize`	number	`3`	Center dot size in pixels
`hoverColor`	string	`-`	Color when hovering interactive elements
`centerDotHoverColor`	string	`-`	Center dot color on hover
`shape`	string	`"circle"`	Cursor shape (circle \| square \| rounded)
`blur`	number	`-`	CSS blur in pixels
`mixBlendMode`	string	`-`	CSS mix-blend-mode (e.g. difference)
`zIndex`	number	`9999`	Cursor z-index
`borderRadius`	string \| number	`-`	Overrides shape border radius
`customCursor`	HTMLElement \| string	`-`	Custom HTML content inside the cursor
`trail`	object	`-`	Ghost trail behind the cursor
`trail.length`	number	`0`	Number of ghost elements (0 disables trail)
`trail.fade`	number	`0.6`	Opacity multiplier for trail ghosts
`trail.scale`	number	`0.95`	Scale falloff per ghost
`clickEffect`	boolean \| object	`-`	Scale pulse on click
`clickEffect.scale`	number	`0.75`	Scale while pressing
`clickEffect.duration`	number	`150`	Restore duration in ms
`magnetic`	boolean \| object	`-`	Snap toward interactive element centers
`magnetic.strength`	number	`0.35`	Pull strength toward element center (0-1)
`magnetic.padding`	number	`40`	Extra hit area around the element in px
`interactiveSelector`	string	`-`	Extra/override CSS selector for interactive elements
`excludeSelector`	string	`-`	Elements matching this selector are never interactive
`hoverEffect`	object	`-`	Effects applied on hover
`hoverEffect.scale`	number	`1.5`	Cursor scale on hover
`hoverEffect.color`	string	`-`	Cursor color on hover
`hoverEffect.opacity`	number	`-`	Cursor opacity on hover
`onHoverInteractive`	function	`-`	Fires when interactive hover state changes
`onClick`	function	`-`	Fires on mouse down

Interactive Elements

Hover over the elements below to see the cursor effects:

Link

Back to projects