Usage

Supermouse operates as a singleton engine, managing input events, physics interpolation, and the plugin queue. Instantiate it once when your application mounts. Refer to the constructor options for a complete parameter reference.

# 1. Configuration

The core runtime requires configuration via a SupermouseOptions argument. You can load plugins declaratively inside the plugins constructor parameter, or register them dynamically using the chainable use() api.

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

const app = new Supermouse({
  plugins: [
    Dot({ size: 8 }),
    Ring({ size: 24 })
  ],
  smoothness: 0.15,
  ignoreOnNative: 'tag'
});

// Also valid:
// app.use(Dot({ ... })).use(Ring({ ... }))

const app = new Supermouse({ smoothness: 0.1 });
app.use(Supermouse.Dot());
app.use(Supermouse.Ring());

# 2. Runtime Registration

Register plugins dynamically at runtime to support conditional scripts, route-based triggers, or lazy-loading configurations.

const app = new Supermouse({ /* options */ });

if (prefersComplexEffects) {
  app.use(Sparkles({ color: 'gold' }));
}

# 3. Defining Interactions

You can define rules to customize cursor behavior per element, either globally during configuration or directly using inline HTML data attributes (e.g. data-supermouse-color="red"). These attributes are scraped automatically and cached efficiently in the background.

To learn more about how attributes are processed, cached, and integrated with TypeScript module augmentation, read the dedicated Interaction State Resolution concept guide.

<!-- Define overrides directly in document markup -->
<button data-supermouse-magnetic="true" data-supermouse-color="red">
  Complex Interaction
</button>

# 4. Scoped Containers

By default, Supermouse appends its rendering stage to document.body and captures window viewport boundaries. Pass a custom container reference to restrict rendering, styles, and hover bounds to a specific element.

// Restrict runtime calculations to a specific element
const modal = document.getElementById('my-modal');

const app = new Supermouse({
  container: modal,
  hideCursor: true
});

// The custom cursor is bounded inside #my-modal.
// Coordinates and stylesheet rules are scoped automatically.

# 5. Manual Visibility

For custom interfaces like canvas games, custom drag-and-drop handles, or text input fields, invoke setNativeCursor() to force cursor overrides.

// Force show the OS native pointer
app.setNativeCursor('show');

// Force hide the OS native pointer
app.setNativeCursor('hide');

// Restore automatic visibility management
app.setNativeCursor('auto');

# 6. Cleanup

// React / Vue / Svelte lifecycle hooks
// Invoke destroy to clear listeners and frame loops on unmount

onUnmounted(() => {
  app.destroy();
});