✨ Aura Cursor

A lightweight, customizable cursor library for modern web applications. Create beautiful custom cursors that follow your mouse with smooth animations and interactive hover effects.

🎮 Try it live

• 🎨 Customizable Design - Size, color, opacity, and speed controls
• 🖱️ Smart Detection - Automatically detects interactive elements (links, buttons, etc.)
• 🎯 Hover Effects - Different styles when hovering over clickable elements
• ⚡ Smooth Animation - Fluid cursor movement with configurable speed
• 🎭 Flexible Options - Hide default cursor, interactive-only mode, outline mode, and more
• 🌈 Hover Colors - Custom colors when hovering over interactive elements
• 📦 Lightweight - Small bundle size with zero dependencies
• 🔧 TypeScript - Full TypeScript support with type definitions
• 👁️ Center Dot Indicator - Small dot in the center when default cursor is hidden or in outline mode, with customizable size and hover colors
• 🪟 Smart Visibility - Automatically hides when mouse leaves the browser window
• 📱 Mobile Accessibility - Automatically disables on mobile devices and small screens for better accessibility

npm install aura-cursor

yarn add aura-cursor

pnpm add aura-cursor

Try Aura Cursor in action: https://andrebarros.dev/projects/aura-cursor

import { AuraCursor } from 'aura-cursor';

// Create cursor instance
const cursor = new AuraCursor({
  size: 20,
  color: '#000000',
  opacity: 0.5,
  speed: 0.3
});

// Initialize the cursor
cursor.init();

<script src="https://unpkg.com/aura-cursor/dist/index.umd.js"></script>
<script>
  const cursor = new AuraCursor.AuraCursor({
    size: 20,
    color: '#000000'
  });
  
  cursor.init();
</script>

import { useAuraCursor } from 'aura-cursor';

function App() {
  useAuraCursor({
    size: 20,
    color: '#000000',
    opacity: 0.5,
    speed: 0.3
  });

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

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

function App() {
  return (
    <>
      <AuraCursor
        size={20}
        color="#000000"
        opacity={0.5}
        speed={0.3}
      />
      <div>Your app content</div>
    </>
  );
}

The component also supports an enabled prop to conditionally enable/disable the cursor:

import { AuraCursor } from 'aura-cursor/react';
import { useState } from 'react';

function App() {
  const [enabled, setEnabled] = useState(true);

  return (
    <>
      <AuraCursor
        enabled={enabled}
        size={20}
        color="#000000"
      />
      <button onClick={() => setEnabled(!enabled)}>
        Toggle Cursor
      </button>
    </>
  );
}

Note: When importing from 'aura-cursor', you get the AuraCursor class. When importing from 'aura-cursor/react', you get the AuraCursor React component. Both share the same name but serve different purposes.

Configure how the cursor changes when hovering over clickable elements:

import { AuraCursor } from 'aura-cursor';

const cursor = new AuraCursor({
  size: 30,
  color: '#ff6b6b',
  opacity: 0.6,
  speed: 0.2
});

cursor.init();

import { AuraCursor } from 'aura-cursor';

const cursor = new AuraCursor({
  size: 20,
  color: '#000000',
  opacity: 0.5,
  hoverEffect: {
    color: '#ff6b6b',
    opacity: 0.8,
    scale: 1.5
  }
});

cursor.init();

import { AuraCursor } from 'aura-cursor';

const cursor = new AuraCursor({
  size: 25,
  color: '#ffffff',
  opacity: 0.7,
  hideDefaultCursor: true,
  centerDotSize: 5,
  centerDotColor: '#ff0000',
  centerDotHoverColor: '#00ff00'
});

cursor.init();

When hideDefaultCursor is enabled, a small center dot will appear to indicate the exact cursor position, following the mouse instantly while the outer circle follows with the configured speed. You can customize the center dot size using centerDotSize (default: 3px) and its color using centerDotColor. When hovering over interactive elements, the center dot will use centerDotHoverColor if provided.

import { AuraCursor } from 'aura-cursor';

const cursor = new AuraCursor({
  size: 20,
  color: '#000000',
  interactiveOnly: true
});

cursor.init();

When interactiveOnly is enabled, the cursor will only appear when hovering over interactive elements (links, buttons, etc.). The cursor will automatically hide when the mouse leaves interactive areas or exits the browser window.

import { AuraCursor } from 'aura-cursor';

const cursor = new AuraCursor({
  size: 20,
  color: '#000000',
  opacity: 0.5,
  outlineMode: true,
  outlineWidth: 2,
  centerDotColor: '#ff0000',
  centerDotSize: 5,
  centerDotHoverColor: '#00ff00'
});

cursor.init();

This mode displays the cursor as a border-only circle with a center dot, instead of a filled circle. The inner dot follows the mouse instantly, while the outer circle follows with a smooth delay. You can customize the border width using the outlineWidth option (default: 2px), the center dot color using centerDotColor, and the center dot size using centerDotSize (default: 3px). When hovering over interactive elements, the center dot will use centerDotHoverColor if provided.

import { AuraCursor } from 'aura-cursor';

const cursor = new AuraCursor({
  size: 20,
  color: '#000000',
  hoverColor: '#ff6b6b',
  hoverEffect: {
    scale: 1.5
  }
});

cursor.init();

The hoverColor option allows you to set a specific color that will be used when hovering over interactive elements. This color takes precedence over the hoverEffect.color option.

import { AuraCursor } from 'aura-cursor';

const cursor = new AuraCursor({
  size: 20,
  color: '#000000'
});

cursor.init();

// Update options later
cursor.updateOptions({
  size: 40,
  color: '#ff0000',
  opacity: 0.8
});

// Remove cursor and clean up
cursor.destroy();

Initializes the custom cursor. Creates the cursor element and attaches event listeners.

cursor.init();

Removes the custom cursor and cleans up all event listeners and DOM elements.

cursor.destroy();

Updates cursor options dynamically without recreating the cursor.

cursor.updateOptions({
  size: 30,
  color: '#ff0000'
});

The library is written in TypeScript and provides full type definitions. All interfaces are exported for use in your TypeScript projects:

import type { 
  AuraCursorOptions, 
  AuraCursorHoverEffectOptions, 
  AuraCursorProps 
} from 'aura-cursor';

// Use the types in your code
const options: AuraCursorOptions = {
  size: 20,
  color: '#000000',
  hoverColor: '#ff0000'
};

// Extend interfaces if needed
interface ExtendedOptions extends AuraCursorOptions {
  customProperty?: string;
}

The cursor automatically detects interactive elements including:

• Links (<a>)
• Buttons (<button>)
• Elements with role="button"
• Elements with onclick handlers
• Elements with cursor: pointer in CSS
• Interactive inputs (range, color, checkbox)
• Elements inside clickable containers

The cursor also automatically hides when the mouse leaves the browser window (e.g., when moving to the address bar or outside the viewport).

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

git clone https://github.com/andrecb/aura-cursor.git
cd aura-cursor

npm install

npm run build

npm test

npm run example

This will build the project and start a local server at http://localhost:8080 with the example page.

This project follows Semantic Versioning (SemVer).

Version numbers follow the pattern: MAJOR.MINOR.PATCH

• MAJOR version when you make incompatible API changes
• MINOR version when you add functionality in a backward compatible manner
• PATCH version when you make backward compatible bug fixes

The project includes npm scripts to help with versioning:

# Bump patch version (1.0.0 -> 1.0.1)
npm run version:patch

# Bump minor version (1.0.0 -> 1.1.0)
npm run version:minor

# Bump major version (1.0.0 -> 2.0.0)
npm run version:major

These scripts will:

1. Update the version in package.json
2. Create a git commit with the version change
3. Create a git tag for the new version

Before releasing a new version:

1. Update the CHANGELOG.md with the changes
2. Run tests: npm run test:run
3. Build the project: npm run build
4. Bump the version using the appropriate script
5. Push to repository: git push && git push --tags
6. Publish to npm: npm publish

Aura Cursor automatically detects mobile devices and small screens to ensure better accessibility. The cursor will not be initialized on:

• Touch-enabled devices (devices with touch support)
• Small screens (width ≤ 768px) with mobile user agents
• Devices that match common mobile user agent patterns

The library also listens for screen size changes and orientation changes, automatically disabling the cursor when switching to mobile view and re-enabling it when switching back to desktop view.

This ensures that:

• Touch interactions are not interfered with on mobile devices
• The cursor doesn't appear on devices where it's not needed
• Performance is optimized by not running unnecessary animations on mobile

MIT © André Barros

Contributions are welcome! Please feel free to submit a Pull Request.

André Barros

• Email: contato@andrebarros.dev
• GitHub: @andrecb

Made with ❤️ by André Barros