React | Supermouse.js

PACKAGE@supermousejs/react

DEPENDENCYreact >= 16.8

LICENSEMIT

The React adapter provides a SupermouseProvider context and a useSupermouse hook. It wraps @supermousejs/core in React's context API and handles cleanup on unmount — including React 18 Strict Mode's double-mount behavior.

01 Installation

Terminal

pnpm add @supermousejs/react @supermousejs/core @supermousejs/dot

02 Root Provider

Wrap your application in SupermouseProvider. This creates the engine instance and makes it available via context. options accepts the same fields as the Supermouse constructor.

src/App.tsx

import { SupermouseProvider } from '@supermousejs/react';
import { Dot } from '@supermousejs/dot';

export default function App() {
  return (
    <SupermouseProvider
      options={{
        smoothness: 0.15,
        hideCursor: true
      }}
      plugins={[
        Dot({ size: 8, color: 'black' })
      ]}
    >
      <YourAppContent />
    </SupermouseProvider>
  );
}

03 Usage in Components

Call useSupermouse() in any descendant component to get the live instance. It returns Supermouse | null — guard before accessing state or calling methods like destroy.

src/components/CustomButton.tsx

import { useSupermouse } from '@supermousejs/react';

export const CustomButton = () => {
  // Returns the Supermouse instance or null before mount
  const mouse = useSupermouse();

  const handleClick = () => {
    if (mouse) {
      console.log('Cursor at:', mouse.state.pointer);
    }
  };

  return <button onClick={handleClick}>Log Position</button>;
};

04 Next.js (App Router)

Because Supermouse accesses window on initialization, it must run on the client. SupermouseProvider is already compiled with "use client" directives, so you can import it directly in a server-rendered layout. For more complex setups, extract it into a dedicated client component.

src/app/layout.tsx

import { SupermouseProvider } from '@supermousejs/react';

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        {/* SupermouseProvider is already marked 'use client' internally */}
        <SupermouseProvider options={{ smoothness: 0.15, hideCursor: true }}>
           {children}
        </SupermouseProvider>
      </body>
    </html>
  );
}

Strict Mode

React 18 Strict Mode mounts components twice in development. SupermouseProvider tracks mount count internally, ensuring only one engine instance is active at a time.