Troubleshooting | Supermouse.js

Custom cursor implementations must coordinate with native browser pointer behaviors. Use this diagnostic matrix to isolate and resolve runtime conflicts.

00 / TOOL

Unknown Conflict

Elements behave inconsistently or multiple cursors appear.

The optional @supermousejs/utils package includes a diagnosticdoctor()utility. It audits the active document layers for inline cursor styles or specificity conflicts that override Supermouse styles.

import { doctor } from '@supermousejs/utils';

doctor(); // Run in browser console

01 / VISUAL

Double Cursor

The native OS cursor flickers or renders on top of the custom cursor.

Usually caused by inline styles (style="cursor: pointer") or high-specificity selector declarations overriding the dynamically injected stage rules. Migrate CSS pointer definitions to programmaticrules.

02 / LAYER

Hidden Behind Modals

Cursor vanishes when opening a dialog, overlay container, or side drawer.

The overlay container has a higher layout priority than the cursor stage. Supermouse mounts overlays between 300-400, but third-party components often use extreme limits like 9999. Configure your CSS theme parameters accordingly.

:root {
  --cursor-z-index: 99999; /* Set higher than modal layer */
}

03 / BROWSER

Stuck on iFrames

Cursor freezes or disappears at the boundary of a video player or map element.

Browsers suspend mouse event dispatching to the host window when hovering iframe embeds. Disable pointer interaction on frame blocks if cursor continuity is required.

iframe {
  pointer-events: none; /* Passes mouse coordinates to parent */
}

04 / ENV

Mobile Ghosts

Interacting on touch screens renders a static cursor node at tap points.

Supermouse is designed to hibernate on coarse pointer contexts viaautoDisableOnMobile. EnsureenableTouchis not set to true.

05 / DEV

React Strict Mode

Duplicate cursors mount in development, or frame listeners run twice.

React 18 mounts effects twice during development. Ensure you calldestroy()on cleanup if not using our official wrapper.

useEffect(() => {
  const app = new Supermouse();
  return () => app.destroy(); 
}, []);

06 / PERF

High Hz Jitter

Damping dynamics stutter or speed up on high-frequency monitors.

Avoid basic frame-count linear interpolations. Visual updates must account for variable hardware refresh rates by using the frame delta parameter (dt) and themath.damp()helper.