Documentation

Quick start

Three lines of code to get your first shapeshifting cursor.

import ProteusCursor from 'proteuscursor';
import 'proteuscursor/style';

const cursor = new ProteusCursor({ shape: 'circle' });

The two modes

All cursor behaviour builds on one of two base modes, set via the shape option.

State machine

Register named cursor states in JavaScript with addState(), then activate them anywhere in HTML with a single data-cursor-state attribute. States revert automatically on mouseleave.

cursor
  .addState('cta', {
    shape_size: '60px',
    shape_color: '#A64B2A',
    text: 'Click',
    text_size: '13px',
  })
  .addState('gallery', {
    shape_size: '100px',
    shape_color: 'rgba(28,25,21,0.1)',
    text: 'Zoom',
  });

<button data-cursor-state="cta">Buy now</button>
<img data-cursor-state="gallery" src="photo.jpg" />

Debug overlay

A read-only panel showing the state machine in real time: the active state, the default preset snapshot, current behaviour flags and the last 10 hover/leave transitions. Purely passive — pointer-events: none, re-renders only on transitions.

cursor.enableDebugOverlay();                             // top-left
cursor.enableDebugOverlay({ position: 'bottom-right' }); // pick a corner
cursor.disableDebugOverlay();

Data attributes

Per-element overrides without registering a named state — useful for one-off hover effects.

<button
  data-proteus-shapeSize="80px"
  data-proteus-shapeColor="#1C1915"
  data-proteus-text="Hello"
  data-proteus-textColor="#F3EFE5"
  data-proteus-textSize="14px"
  data-proteus-shadowIsEnabled="true"
>
  Hover me
</button>

Constructor options

All options passed to new ProteusCursor(options).

Setters

All setters can be called at runtime. Most accept an optional isPermanent flag — when true, the value persists after state resets.

Static methods & properties

Class-level utilities. Call without creating an instance.

Preset system

Five built-in configurations. Apply in one line and override any property. Hover the entries to preview.

const cursor = new ProteusCursor({ shape: 'circle' });

// apply to a live instance (chainable)
cursor.loadPreset('neon');
cursor.loadPreset('chrome', { shape_size: '64px' }); // with overrides

// use as constructor base
const cursor2 = new ProteusCursor({
  ...ProteusCursor.getPreset('neon'),
  shape_color: '#ff4444',
});

Blend mode

Apply a CSS mix-blend-mode to the cursor shape. 'difference' with a white cursor inverts whatever it crosses — perfect contrast on any background.

new ProteusCursor({
  shape: 'circle',
  shape_size: '40px',
  shape_color: '#ffffff',
  hasShadow: false,
  blend_mode: 'difference',
});

// runtime or per state
cursor.setBlendMode('exclusion');
cursor.addState('hero', { shape_color: '#ffffff', blend_mode: 'difference' });

Click animations

Feedback on every mousedown: 'scale' shrinks and springs back, 'ripple' expands a fading circle from the click point, 'none' disables it.

new ProteusCursor({
  shape: 'circle',
  click_animation: 'ripple', // 'scale' | 'ripple' | 'none'
  click_duration: 300,       // ms
});

Magnetic behavior

While hovering an interactive element, the cursor is pulled toward its centre and eases back on leave. With magnetic_parallax, the element itself leans a few clamped pixels toward the cursor — a separate opt-in; each works with or without the other.

new ProteusCursor({
  shape: 'circle',
  magnetic: true,
  magnetic_strength: 0.4,   // 0–1, snappiness
  magnetic_radius: null,    // px falloff, null = full pull
  magnetic_targets: 'a, button, [data-cursor-magnetic]',
  magnetic_parallax: true,
  magnetic_parallax_strength: 0.15,
});

// runtime (chainable)
cursor.setMagnetic(true);
cursor.setMagneticStrength(0.6, true);
cursor.setMagneticParallax(true);

Any element can opt in via the data attribute included in the default selector:

<div data-cursor-magnetic>Hover me</div>

Framework adapters

First-class hooks for React, Vue 3 and Svelte via subpath exports. Each handles mount/unmount automatically and is SSR-safe — the constructor runs only on the client.

import { useProteusCursor } from 'proteuscursor/react';
import 'proteuscursor/style';

const cursor = useProteusCursor({ shape: 'circle' });
// cursor.current → instance (null until mounted)

import { useProteusCursor } from 'proteuscursor/vue';
import 'proteuscursor/style';

const cursor = useProteusCursor({ shape: 'circle' });
// cursor.value → instance (null until mounted)

import { useProteusCursor } from 'proteuscursor/svelte';
import 'proteuscursor/style';

const cursor = useProteusCursor({ shape: 'circle' });
// cursor.current → instance (undefined until mounted)

Touch & reduced motion

Inclusive by default. On touch-only devices (detected via pointer: coarse) and under prefers-reduced-motion: reduce, Proteus skips initialization entirely — no DOM elements, no listeners, native cursor preserved. Every API method remains safe to call as a no-op.

// opt out of the reduced-motion check
new ProteusCursor({ shape: 'circle', respectReducedMotion: false });

// or keep a branded, motionless cursor instead of the native one
new ProteusCursor({ shape: 'circle', reducedMotionFallback: 'static' });

cursor.isStaticFallback;                 // which mode you got
ProteusCursor.isTouchOnly();             // your own branching
ProteusCursor.prefersReducedMotion();