Skip to main content

@theforce/react

React integration for TheForce Hand Tracking Library. This package provides a HandTrackerProvider component and a useHandTracker hook to easily integrate hand tracking into your React applications.

Installation​

npm install @theforce/react @theforce/core
# or
yarn add @theforce/react @theforce/core

Important Note on Mediapipe Dependency:​

For TheForce to function correctly, you must include the Mediapipe library from a CDN in your project's index.html (or equivalent entry point). This is a runtime dependency required by @theforce/core.

Please add the following script tags to your HTML file's <head> or before your main application script:

<script src="https://cdn.jsdelivr.net/npm/@mediapipe/camera_utils/camera_utils.js" crossorigin="anonymous"></script>
<script src="https://cdn.jsdelivr.net/npm/@mediapipe/hands/hands.js" crossorigin="anonymous"></script>

Quick Start​

Wrap your application or the relevant part of your component tree with HandTrackerProvider.

import React, { useEffect } from "react";
import { HandTrackerProvider, useHandTracker } from "@theforce/react";

function HandTrackingDemo() {
  const { isTracking, initialize, stop } = useHandTracker();

  useEffect(() => {
    // Initialize tracking when the component mounts
    initialize();

    return () => {
      // Stop tracking when the component unmounts
      stop();
    };
  }, []);

  const handleButtonClick = (button) => {
    const currentCount = parseInt(
      button.target.getAttribute("data-count") || "0",
      10,
    );
    button.target.setAttribute("data-count", currentCount + 1);
    button.target.textContent = `Button Clicked ${currentCount + 1} times`;
  };

  return (
    <>
      <button
        data-hoverable="true"
        onClick={handleButtonClick}
        style={{
          position: "fixed",
          top: "50%",
          left: "50%",
          transform: "translate(-50%, -50%)",
        }}
      >
        Button Clicked 0 times
      </button>
    </>
  );
}

function App() {
  const config = {
    hoverDelay: 1000,
    sensitivityX: 1.5,
    sensitivityY: 1.5,
  };

  return (
    <HandTrackerProvider config={config} debug={true}>
      <HandTrackingDemo />
    </HandTrackerProvider>
  );
}

export default App;

HandTrackerProvider Props​

PropTypeDefaultDescription
configobject{}Configuration object for the underlying HandTracker instance. See @theforce/core documentation for available options like hoverDelay, sensitivityX, sensitivityY, cursorImageUrl, cursorLandmarkIndex.
debugbooleanfalseIf true, the camera feed will be displayed in the bottom right corner for debugging purposes.

useHandTracker Hook​

This hook provides access to the hand tracking state and control functions.

const { handLandmarks, isTracking, initialize, stop } = useHandTracker();
PropertyTypeDescription
handLandmarksArray<any>An array of detected hand landmarks. Empty if no hands are detected.
isTrackingbooleantrue if hand tracking is active, false otherwise.
initialize() => Promise<void>Function to initialize and start hand tracking.
stop() => Promise<void>Function to stop hand tracking and clean up resources.

Styling Hoverable Elements​

Elements marked with data-hoverable="true" will have the following CSS classes applied by the core library, which you can style:

  • .force-hoverable: Always present on elements with data-hoverable="true".
  • .force-hover: Added when the virtual cursor is hovering over the element.

For the virtual cursor itself, you can style the .force-cursor and .force-loading classes. Refer to the @theforce/core documentation for more details.