Hammer.js Multi-touch Gestures

Common errors

• ReferenceError: window is not defined

  cause Hammer.js is a browser-only library and attempts to access the global `window` object during initialization in a Server-Side Rendering (SSR) environment.
  fix Conditionally load Hammer.js only on the client-side using dynamic imports or ensure its initialization is deferred until the browser environment is available.

• Uncaught ReferenceError: TOUCH_ACTION_COMPUTE is not defined

  cause This error often occurs when the incorrect Hammer.js file is loaded, typically a source file (e.g., from `/src` directory) instead of the compiled distribution file.
  fix Verify that your HTML script tag or module bundler is pointing to the correct Hammer.js distribution file, usually `node_modules/hammerjs/hammer.js`.

• Cannot find namespace 'Hammer'.

  cause This is a TypeScript error indicating that the TypeScript compiler cannot find type definitions for the global `Hammer` object.
  fix Install the type definitions package: `npm install --save-dev @types/hammerjs`.

• Gesture is not recognized or conflicts (e.g., pan and pinch at the same time, swipe not firing)

  cause Default configurations for gestures might be too restrictive (e.g., `pinch` and `rotate` are disabled by default), or conflicts exist between recognizers with overlapping conditions (e.g., horizontal pan and swipe).
  fix Explicitly enable disabled recognizers (e.g., `mc.get('pinch').set({ enable: true });`). Adjust `direction` (e.g., `Hammer.DIRECTION_ALL`) and `threshold` options for recognizers to resolve conflicts and ensure proper detection. For complex interactions, use `recognizeWith` or `requireFailure`.

Warnings

• breaking Migrating from Hammer.js v1.x to v2.x involves significant breaking changes. The library was completely rewritten, deprecating many gestures and introducing an entirely new API for recognizers and event management.
  Fix: Review the official Hammer.js v2.0 documentation carefully for API changes. Existing v1.x code will require substantial refactoring.
• deprecated The original `hammerjs` package is no longer actively maintained, with its last release being in April 2016. Users are encouraged to consider modern browser APIs for gesture handling or use alternative, actively maintained libraries. Angular, for example, has deprecated its direct HammerJS integration.
  Fix: For new projects, evaluate alternatives like `@use-gesture` or native DOM touch events. For existing projects, consider forks like `@egjs/hammerjs` if you require continued maintenance or specific features like ESM support.
• gotcha Hammer.js can conflict with Server-Side Rendering (SSR) environments, throwing a `ReferenceError: window is not defined` because it expects a browser `window` object to be present on initialization.
  Fix: Implement dynamic imports or conditional loading to ensure Hammer.js is only initialized client-side. For Webpack, `bundle-loader` can be used. Ensure all gesture-related logic runs after the component has mounted (e.g., `componentDidMount` in React or `ngAfterViewInit` in Angular).
• gotcha Common pitfalls include gesture conflicts (e.g., pan vs. swipe threshold settings, pinch with pan), performance issues from excessive event listeners, and memory leaks if event listeners are not properly cleaned up.
  Fix: Carefully configure recognizer options (like `direction`, `threshold`) to avoid conflicts. Use `Hammer.Manager` for complex scenarios to manage recognizers effectively. Ensure `mc.destroy()` is called or `mc.off()` is used to remove listeners when elements are removed from the DOM or components unmount.
• gotcha Incorrectly referencing the Hammer.js file (e.g., `node_modules/hammerjs/src/hammer.js` instead of `node_modules/hammerjs/hammer.js`) can lead to `Uncaught ReferenceError` errors for internal Hammer.js variables like `TOUCH_ACTION_COMPUTE` or `ifUndefined`.
  Fix: Always ensure you are referencing the correct, pre-built distribution file (`hammer.js`) and not raw source files when including the library directly in HTML or bundling.

Install

• npm install hammerjs npm
• yarn add hammerjs yarn
• pnpm add hammerjs pnpm

Imports

• Hammer
  wrong:

  import Hammer from 'hammerjs';

  correct:

  <!-- In HTML: -->
  <script src="path/to/hammer.js"></script>
  <script>
    const mc = new Hammer.Manager(element);
  </script>

  The official `hammerjs` package (v2.x) does not provide a direct ES module export and exposes 'Hammer' as a global variable. For ES module support, consider the `@egjs/hammerjs` fork.
• Hammer

  const Hammer = require('hammerjs');
  const mc = new Hammer.Manager(element);

  CommonJS import for Node.js environments (though primarily a browser library). Note that this still expects `Hammer` to be globally exposed or bundled via UMD.
• Hammer.Manager, Hammer.Rotate
  wrong:

  import { Manager, Rotate } from 'hammerjs'; // Incorrect named import for v2.x

  correct:

  declare var Hammer: any; // For global Hammer object in TypeScript
  const mc = new Hammer.Manager(document.getElementById('myElement'));
  const rotate = new Hammer.Rotate();
  mc.add(rotate);

  For TypeScript usage, install `@types/hammerjs` to get type definitions. The `Hammer` object itself contains nested classes like `Manager` and `Rotate`.

Quickstart

This example demonstrates how to initialize Hammer.js on an element, add a rotation recognizer, and listen for the 'rotate' event to dynamically transform the element. It also includes a basic tap event example.

document.addEventListener('DOMContentLoaded', () => {
  const stage = document.getElementById('stage');
  if (!stage) {
    console.error('Element with ID "stage" not found.');
    return;
  }

  // Create a manager for that element
  const mc = new Hammer.Manager(stage);

  // Create a recognizer for rotation
  const rotateRecognizer = new Hammer.Rotate();

  // Add the recognizer to the manager and enable it (pinch and rotate are often disabled by default)
  mc.add(rotateRecognizer);
  mc.get('rotate').set({ enable: true });

  // Subscribe to the rotate event
  mc.on('rotate', function(e) {
    const rotation = Math.round(e.rotation);
    stage.style.transform = `rotate(${rotation}deg)`;
    console.log(`Rotation: ${rotation} degrees`);
  });

  // Example for a simple tap recognizer
  const tapRecognizer = new Hammer.Tap();
  mc.add(tapRecognizer);
  mc.on('tap', function(e) {
    console.log('Tap detected!', e.target);
    e.target.style.backgroundColor = 'lightblue';
    setTimeout(() => e.target.style.backgroundColor = 'transparent', 200);
  });

  // Enable pinch and pan for demonstration, if desired
  mc.get('pinch').set({ enable: true });
  mc.get('pan').set({ direction: Hammer.DIRECTION_ALL });

  console.log('Hammer.js initialized on #stage.');
});