---
description: "Interactive container providing pan and zoom navigation with touch gesture support, mouse wheel zoom, and programmatic control."
---
# ef-pan-zoom
## Attributes
- **x** (number, default: 0) - Horizontal pan offset in pixels
- **y** (number, default: 0) - Vertical pan offset in pixels
- **scale** (number, default: 1) - Zoom scale factor (0.1 to 5)
- **auto-fit** (boolean, default: false) - Auto-fit content on first render
## Methods
- **screenToCanvas(screenX: number, screenY: number): { x: number, y: number }** - Convert screen coordinates to canvas coordinates
- Returns: Object with x, y in canvas space
- **canvasToScreen(canvasX: number, canvasY: number): { x: number, y: number }** - Convert canvas coordinates to screen coordinates
- Returns: Object with x, y in screen space
- **reset(): void** - Reset to default transform (x=0, y=0, scale=1)
- Returns: void
- **fitToContent(padding?: number): void** - Fit content to container with optional padding (0-1)
- Returns: void
# PanZoom
Interactive pan and zoom container with mouse/trackpad gesture support.
## Import
```tsx
import { PanZoom } from "@editframe/react";
```
## Basic Usage
Wrap any content to make it pannable and zoomable:
```html live
```
> **Interaction:** Click and drag to pan. Hold Cmd/Ctrl and scroll to zoom. Scroll to pan horizontally/vertically.
```tsx
import { PanZoom, Timegroup, Video } from "@editframe/react";
```
**Interaction:**
- Click and drag to pan
- Cmd/Ctrl + scroll to zoom
- Two-finger trackpad gestures for pan/zoom
## Auto-Fit Content
Automatically fit content to the container on load:
```html live
```
The `auto-fit` attribute centers and scales content to fit with 5% padding.
```tsx
```
The `autoFit` prop centers and scales content to fit with 5% padding.
## Gesture Controls
### Panning
Click and drag anywhere to pan the view:
```html live
Drag to pan
```
### Zooming
Hold Cmd (Mac) or Ctrl (Windows/Linux) and scroll to zoom:
```html live
Cmd/Ctrl + Scroll to zoom
```
Zoom is centered on the cursor position — the point under the cursor remains fixed while zooming.
### Trackpad Gestures
- **Two-finger drag:** Pan horizontally and vertically
- **Pinch:** Zoom in/out (with Cmd/Ctrl)
- **Scroll:** Pan without modifier keys
- **Click and drag:** Pan in any direction
- **Two-finger drag (trackpad):** Pan horizontally and vertically
- **Scroll:** Pan without modifier keys
### Zooming
- **Cmd/Ctrl + scroll:** Zoom in/out
- **Pinch (trackpad):** Zoom with Cmd/Ctrl modifier
Zoom is centered on the cursor position — the point under the cursor remains fixed while zooming.
## Programmatic Control
Set transform properties directly:
```html live
Programmatic Transform
```
Control transform with props:
```tsx
import { useState } from "react";
import { PanZoom, Timegroup, Video } from "@editframe/react";
const ZoomablePreview = () => {
const [x, setX] = useState(0);
const [y, setY] = useState(0);
const [scale, setScale] = useState(1);
return (
);
};
```
## Methods
### reset()
Reset the view to default values:
```javascript
const panZoom = document.querySelector('ef-pan-zoom');
panZoom.reset(); // x=0, y=0, scale=1
```
```tsx
import { useRef } from "react";
import { PanZoom } from "@editframe/react";
import type { EFPanZoom } from "@editframe/elements";
const panZoomRef = useRef(null);
panZoomRef.current?.reset();
```
### fitToContent(padding)
Fit content to the container:
```javascript
const panZoom = document.querySelector('ef-pan-zoom');
panZoom.fitToContent(0.1); // 10% padding on each side
```
```tsx
panZoomRef.current?.fitToContent(0.1); // 10% padding
```
Padding is a factor from 0 to 1, where 0.1 = 10% padding.
### screenToCanvas(screenX, screenY)
Convert screen coordinates (e.g., mouse event) to canvas coordinates:
```javascript
panZoom.addEventListener('click', (e) => {
const canvasPos = panZoom.screenToCanvas(e.clientX, e.clientY);
console.log(`Clicked at canvas position: ${canvasPos.x}, ${canvasPos.y}`);
});
```
```tsx
const canvasPos = panZoomRef.current?.screenToCanvas(e.clientX, e.clientY);
```
Useful for hit detection and positioning elements in canvas space.
### canvasToScreen(canvasX, canvasY)
Convert canvas coordinates to screen coordinates:
```javascript
const screenPos = panZoom.canvasToScreen(element.x, element.y);
tooltip.style.left = `${screenPos.x}px`;
tooltip.style.top = `${screenPos.y}px`;
```
```tsx
const screenPos = panZoomRef.current?.canvasToScreen(canvasX, canvasY);
```
Useful for positioning overlays and tooltips relative to canvas elements.
## Events
### transform-changed
Fired when pan or zoom changes:
```javascript
panZoom.addEventListener('transform-changed', (e) => {
console.log('Transform:', e.detail); // { x, y, scale }
});
```
Use this to sync UI controls or persist view state.
```tsx
{
console.log('Transform:', e.detail); // { x, y, scale }
}}
className="w-[500px] h-[300px]"
>
Pan and zoom me
```
## Context Provision
`ef-pan-zoom` provides transform data via Lit context. Child components can consume this to render overlays that match the transform:
```javascript
import { consume } from '@lit/context';
import { panZoomTransformContext } from '@editframe/elements';
@consume({ context: panZoomTransformContext })
panZoomTransform?: PanZoomTransform;
```
Overlay components (like selection handles) use this to align with the panned/zoomed content.
## With Ref for Methods
Access underlying element methods using ref:
```tsx
import { useRef } from "react";
import { PanZoom } from "@editframe/react";
import type { EFPanZoom } from "@editframe/elements";
const PanZoomWithControls = () => {
const panZoomRef = useRef(null);
const handleReset = () => {
panZoomRef.current?.reset();
};
const handleFitContent = () => {
panZoomRef.current?.fitToContent(0.1); // 10% padding
};
return (
{/* Content */}
);
};
```
### Available Methods
- `reset()` - Reset to default transform (x=0, y=0, scale=1)
- `fitToContent(padding?: number)` - Fit content to container with optional padding (0-1)
- `screenToCanvas(screenX: number, screenY: number)` - Convert screen coordinates to canvas coordinates
- `canvasToScreen(canvasX: number, canvasY: number)` - Convert canvas coordinates to screen coordinates
## With usePanZoomTransform Hook
Use the `usePanZoomTransform` hook to access transform data in child components:
```tsx
import { PanZoom, usePanZoomTransform } from "@editframe/react";
const TransformDisplay = () => {
const transform = usePanZoomTransform();
return (
);
};
```
## Video Preview with Pan-Zoom
Create a zoomable video preview:
```html live
Zoomable Preview
Cmd/Ctrl + Scroll to zoom
```
```tsx
import { PanZoom, Timegroup, Video, Text } from "@editframe/react";
export const VideoEditorPreview = () => {
return (
Zoomable Preview
Cmd/Ctrl + Scroll to zoom • Click and drag to pan
);
};
```
## Styling
The element has `overflow: hidden` and `position: relative` by default. Style the container as needed:
```html
```
The component has `overflow: hidden` and `position: relative` by default. Add custom styles via `className`:
```tsx
{/* Content */}
```
## Scale Limits
Scale is clamped between 0.1 and 5:
- Minimum: 0.1 (10% of original size)
- Maximum: 5 (500% of original size)
These limits prevent unusable zoom levels while allowing meaningful magnification.
## Browser Navigation Prevention
`ef-pan-zoom` prevents browser back/forward navigation triggered by trackpad swipes. This ensures pan gestures don't accidentally navigate away from the page.
The element uses passive event listeners in capture phase to intercept and prevent default navigation behavior while still allowing normal pan/zoom interactions.
## TypeScript Types
```tsx
import type { PanZoomTransform } from "@editframe/elements";
// Transform structure
interface PanZoomTransform {
x: number;
y: number;
scale: number;
}
```