Pointer Capture and Transform Coordination

Pan-zoom elements use pointer capture to ensure smooth, reliable panning interactions across different input devices and scenarios.

The Challenge

When implementing pan interactions, pointer events can be lost if the pointer moves outside the element boundaries during dragging. This creates a poor user experience where panning stops unexpectedly when the cursor leaves the element area. Additionally, coordinating transform updates with pointer movements requires careful state management to prevent jitter and ensure consistent behavior.

The Solution

Pan-zoom elements use pointer capture to maintain control of pointer events even when the pointer moves outside the element. When a pointer down event occurs, the element captures the pointer, ensuring all subsequent move and up events are delivered to the element regardless of pointer position. This enables smooth panning that continues even when the cursor moves outside the viewport.

The transform is calculated by tracking the delta between the initial pointer position and current position, then applying that delta inversely to the transform. This approach provides predictable, smooth panning behavior.

<ef-pan-zoom class="w-[720px] h-[480px] border-2 border-gray-300 overflow-hidden bg-gray-100">
  <div class="w-[1200px] h-[800px] bg-gradient-to-br from-blue-400 to-purple-500 flex items-center justify-center text-white text-2xl text-center p-8">
    Start dragging and move cursor outside — panning continues
  </div>
</ef-pan-zoom>

Benefits

Pointer capture provides reliable panning that works consistently across mouse, touch, and stylus inputs. Users can drag content smoothly without losing control when the pointer temporarily leaves the element area. The transform coordination ensures that pan movements feel natural and responsive, with updates happening immediately as the pointer moves.

This approach eliminates the common problem of panning stopping unexpectedly, creating a more polished and professional interaction experience. The element handles pointer lifecycle management automatically, including cleanup on pointer up or cancel events.

---

Zoom-to-Pointer Behavior

Pan-zoom elements zoom centered on the pointer position, creating an intuitive exploration experience where the content under the cursor remains stable during zoom operations.

The Challenge

When zooming content, the zoom center point determines what part of the content remains visible. Zooming from a fixed center (like the viewport center) creates a disorienting experience where the content under the cursor moves away during zoom. Users expect the content they're pointing at to stay in place, with surrounding content expanding or contracting around that point.

The Solution

Pan-zoom elements calculate zoom operations relative to the pointer position. When a zoom gesture occurs (wheel with modifier key), the element identifies the point under the pointer in both viewport coordinates and content coordinates. It then adjusts both the scale and pan position so that the content point under the pointer remains visually stable, while the rest of the content scales around it.

This requires converting between coordinate spaces: from viewport coordinates (where the pointer is) to content coordinates (what content is at that point), then back to viewport coordinates after applying the new scale.

<ef-pan-zoom class="w-[720px] h-[480px] border-2 border-gray-300 overflow-hidden bg-gray-100">
  <div class="w-[1200px] h-[800px] bg-gradient-to-br from-green-400 to-blue-500 flex items-center justify-center text-white text-2xl text-center p-8">
    Hover over a point and zoom (Cmd/Ctrl + Scroll) — it stays centered
  </div>
</ef-pan-zoom>

Benefits

Zoom-to-pointer behavior creates an intuitive exploration experience that matches user expectations. The content under the cursor remains visually stable during zoom, making it easy to zoom into specific areas of interest. This behavior is consistent with common graphics applications and mapping interfaces, reducing the learning curve for users.

The coordinate space conversion happens automatically, so developers don't need to manually calculate zoom centers or adjust pan positions. The element handles the mathematical complexity, providing a simple API that "just works" for users.

The same coordinate conversion utilities are exposed as screenToCanvas() and canvasToScreen() methods, which are useful for positioning overlays and performing hit detection in canvas space. See the Pan-Zoom reference for the full API.