Halo Cursor – Framework‑Agnostic Animated Cursor

Halo Cursor is a lightweight, framework‑agnostic animated cursor halo for modern web apps. It follows the pointer, highlights interactive elements, and can completely hide the native cursor – all in plain TypeScript with zero runtime dependencies. (demo)

It works great with:

• Angular
• React
• Vue
• Svelte
• plain HTML / TypeScript / JavaScript

---

Key Features

• Framework‑agnostic – Works in any app that can run JavaScript in the browser
• Animated halo – Smooth lerped motion with inner dot + outer halo
• Interactive‑aware – Highlights buttons/links and other interactive elements
• Motion‑safe – Respects prefers-reduced-motion and coarse pointers (e.g. touch)
• Cursor control – Optional full native cursor hiding with hideNativeCursor
• Scoped & controllable – Scope to a container with rootElement, and use pause / resume
• Tiny & dependency‑free – Just one class and sensible defaults

Installation

# npm
npm install @andreasnicolaou/halo-cursor

# yarn
yarn add @andreasnicolaou/halo-cursor

# pnpm
pnpm add @andreasnicolaou/halo-cursor

CDN / Direct Usage (UMD)

<!-- unpkg CDN (latest version, unminified) -->
<script src="https://unpkg.com/@andreasnicolaou/halo-cursor/dist/index.umd.js"></script>

<!-- unpkg CDN (latest version, minified) -->
<script src="https://unpkg.com/@andreasnicolaou/halo-cursor/dist/index.umd.min.js"></script>

<!-- jsDelivr CDN (unminified) -->
<script src="https://cdn.jsdelivr.net/npm/@andreasnicolaou/halo-cursor/dist/index.umd.js"></script>

<!-- jsDelivr CDN (minified) -->
<script src="https://cdn.jsdelivr.net/npm/@andreasnicolaou/halo-cursor/dist/index.umd.min.js"></script>

UMD (global halo variable):

<script src="https://unpkg.com/@andreasnicolaou/halo-cursor/dist/index.umd.min.js"></script>
<script>
  // window.halo is the UMD global
  const cursor = new halo.Cursor({
    hideNativeCursor: true,
  });

  cursor.mount();

  // later: cursor.destroy();
</script>

ESM (recommended for bundlers)

import { Cursor } from '@andreasnicolaou/halo-cursor';

const cursor = new Cursor({
  outerSize: 40,
  innerSize: 8,
  hideNativeCursor: true,
});

cursor.mount();

CJS (Node / CommonJS)

const { Cursor } = require('@andreasnicolaou/halo-cursor');

const cursor = new Cursor({
  hideNativeCursor: true,
});

cursor.mount();

Quick Usage Example

import { Cursor } from '@andreasnicolaou/halo-cursor';

const cursor = new Cursor({
  color: '#6366f1',
  hoverColor: '#818cf8',
  outerSize: 36,
  hoverOuterSize: 52,
  hideNativeCursor: true,
  lerp: 0.12,
});

// Attach to the whole document
cursor.mount();

// Temporarily pause animation/interaction (e.g. while a modal is open)
cursor.pause();
cursor.resume();

// Clean up when leaving the page / unmounting your app
// cursor.destroy();

API

Cursor methods

Method	Description
new Cursor(options?)	Creates a new halo cursor instance with the given options.
mount()	Injects styles, creates DOM elements, attaches events, and starts the animation loop.
destroy()	Stops the loop, removes event listeners, DOM nodes, and restores the native cursor.
updateOptions(options)	Merges new options into the existing ones and reinjects the stylesheet while mounted.
pause()	Temporarily pauses tracking and hides the halo off‑screen without destroying the instance.
resume()	Resumes tracking and animation after a previous pause().

CursorOptions

Property	Type	Default	Description
outerSize	number	36	Size of the outer halo ring in pixels
innerSize	number	6	Size of the inner dot in pixels
hoverOuterSize	number	52	Outer ring size on hover
clickOuterSize	number	26	Outer ring size on click
color	string	'#6366f1'	Base color of the cursor halo
hoverColor	string	'#818cf8'	Color on hover state
outerBorderColor	string	'rgba(99, 102, 241, 0.7)'	Outer ring border color
hoverBorderColor	string	'rgba(129, 140, 248, 1)'	Outer ring border color on hover
outerBackground	string	'transparent'	Outer ring background fill
hoverBackground	string	'rgba(99, 102, 241, 0.08)'	Background fill on hover
clickBackground	string	'rgba(99, 102, 241, 0.18)'	Background fill on click
zIndex	number	9999	CSS z-index for cursor elements
lerp	number	0.12	Smoothing factor for cursor movement (0–1, clamped). Higher = snappier, lower = smoother/more lag
hideNativeCursor	boolean	false	Hide the native browser cursor
interactiveSelectors	string	'a, button, [role="button"], input, textarea, select, label, [tabindex="0"]'	CSS selectors for interactive elements
classPrefix	string	'halo-cursor'	CSS class name prefix for generated elements
disableOnReducedMotion	boolean	true	Disable animations if reduced motion is preferred
rootElement	HTMLElement | null	null	Root element to mount cursor into

Framework Examples

Angular

import { AfterViewInit, Component, ElementRef, OnDestroy, ViewChild } from '@angular/core';
import { Cursor } from '@andreasnicolaou/halo-cursor';

@Component({
  selector: 'app-root',
  template: ` <div #scope class="app-shell"><ng-content></ng-content></div> `,
})
export class AppComponent implements AfterViewInit, OnDestroy {
  @ViewChild('scope', { static: true }) scopeRef!: ElementRef<HTMLDivElement>;

  private cursor: Cursor | null = null;

  ngAfterViewInit(): void {
    this.cursor = new Cursor({ rootElement: this.scopeRef.nativeElement, hideNativeCursor: true });
    this.cursor.mount();
  }

  ngOnDestroy(): void {
    this.cursor?.destroy();
  }
}

React

import { useEffect, useRef } from 'react';
import { Cursor } from '@andreasnicolaou/halo-cursor';

export function AppCursorScope() {
  const ref = useRef<HTMLDivElement | null>(null);

  useEffect(() => {
    if (!ref.current) return;

    const cursor = new Cursor({ rootElement: ref.current, hideNativeCursor: true });
    cursor.mount();

    return () => cursor.destroy();
  }, []);

  return <div ref={ref}>{/* your app */}</div>;
}

Vue

import { onBeforeUnmount, onMounted, ref } from 'vue';
import { Cursor } from '@andreasnicolaou/halo-cursor';

const scopeRef = ref<HTMLElement | null>(null);
let cursor: Cursor | null = null;

onMounted(() => {
  if (!scopeRef.value) return;
  cursor = new Cursor({ rootElement: scopeRef.value, hideNativeCursor: true });
  cursor.mount();
});

onBeforeUnmount(() => {
  cursor?.destroy();
});

Use in your template:

<template>
  <div ref="scopeRef">
    <!-- your content -->
  </div>
</template>

Notes & Accessibility

• The cursor auto‑disables itself on coarse pointers (e.g. touch devices).
• When disableOnReducedMotion is true (default), it also disables itself when prefers-reduced-motion: reduce is enabled.
• All DOM access happens inside mount() / destroy(), keeping the class safe to instantiate in SSR environments.

---

Contributing

Contributions, ideas, and bug reports are welcome. Feel free to open an issue or PR on the GitHub repository.