Installation | Supermouse.js

01 Via Package Manager

Install scoped packages to optimize tree-shaking and bundle footprint.

Terminal

pnpm add @supermousejs/core @supermousejs/dot @supermousejs/ring

Alternatively, you can install the unscoped bundle which contains standard defaults:

Terminal

pnpm install supermousejs

02 CDN / Direct Script

For projects without a bundler, load the compiled package via unpkg or jsDelivr. This exposes the core constructor alongside standard Dot and Ring visual hooks on the global namespace.

index.html

<script src="https://unpkg.com/supermousejs"></script>

<script>
  const { Dot, Ring } = Supermouse;

  const app = new Supermouse();
  app.use(Dot()).use(Ring());
</script>

03 Initialize (Modules)

Instantiate the runtime within your application entry point (e.g. main.ts or a root lifecycle wrapper).

src/main.ts

import { Supermouse } from '@supermousejs/core';
import { Dot } from '@supermousejs/dot';
import { Ring } from '@supermousejs/ring';

const app = new Supermouse({
  smoothness: 0.12,
  hideCursor: true
});

app.use(Dot({ size: 8, color: '#f0f' })).use(Ring({ size: 20 }));

04 Markup Control

Visual plugins watch for configured data attributes in the document markup automatically.

index.html

<div data-supermouse-color="#00ff00">Color override</div>
<a data-supermouse-img="/path/to/img.jpg">Show image on hover</a>

Warning: CSS Conflicts

Do not define cursor: pointer or cursor: none rules in your application stylesheets.

Supermouse handles native pointer visibility dynamically. Ad-hoc CSS cursor overrides bypass target detection and cause double-cursor rendering or cursor flickering. Define hover affordances programmatically using rules configurations.

To manage edge-cases or resolve browser conflicts, see the troubleshooting guide . Configure the hideCursor and ignoreOnNative parameters for detailed granularity.