Canvas Controls Plugin

The Canvas Controls plugin provides navigation controls for the infinite canvas including zooming, panning, and scrolling.

Try it

• Scroll wheel to pan
• Ctrl/Cmd + scroll to zoom
• Hand tool or middle mouse to drag-pan with momentum

Usage

The Canvas Controls plugin is included by default when using WovenCanvas. To configure it:

<template>
  <WovenCanvas
    :plugin-options="{
      controls: { minZoom: 0.1, maxZoom: 5 }
    }"
  />
</template>

To disable it:

<template>
  <WovenCanvas :plugin-options="{ controls: false }" />
</template>

Options

Option	Type	Default	Description
minZoom	number	0.05	Minimum zoom level (5%)
maxZoom	number	2.7	Maximum zoom level (270%)
smoothScroll	{ enabled, time }	{ enabled: true, time: 0.12 }	Smooth scroll tweening options
cameraBounds	CameraBounds	undefined	Restrict the camera viewport to a rectangular region

CanvasControlsPlugin({
  minZoom: 0.1,  // 10% minimum zoom
  maxZoom: 5,    // 500% maximum zoom
})

Controls

Input	Action
Scroll wheel	Pan the canvas
Ctrl/Cmd + Scroll wheel	Zoom in/out toward cursor
Middle mouse drag	Pan with momentum (glide)
Hand tool drag	Pan with momentum (glide)

Pan States

The plugin maintains internal pan state for smooth momentum-based panning:

State	Description
Idle	No panning in progress
Panning	User is actively dragging
Gliding	Momentum-based movement after release

Camera Bounds

You can restrict the camera viewport to a rectangular region in world coordinates using the cameraBounds option:

CanvasControlsPlugin({
  cameraBounds: {
    top: 0,
    bottom: 2000,
    left: 0,
    right: 3000,
    restrict: 'edges', // 'edges' or 'center'
  },
})

Property	Type	Default	Description
top	number	—	Top edge of the bounds in world coordinates
bottom	number	—	Bottom edge of the bounds in world coordinates
left	number	—	Left edge of the bounds in world coordinates
right	number	—	Right edge of the bounds in world coordinates
restrict	'edges' | 'center'	'edges'	'edges': no viewport edge can extend past bounds. 'center': viewport center cannot leave bounds

## Programmatic Camera Control

You can control the camera programmatically using the editor API:

```typescript
import { Camera } from '@woven-canvas/core'

editor.nextTick((ctx) => {
  const camera = Camera.write(ctx)

  // Set position (world coordinates)
  camera.position[0] = 500
  camera.position[1] = 300

  // Set zoom level
  camera.zoom = 1.5
})

Smooth Camera Glide

To smoothly animate the camera to center on a world position, use the GlideToPosition command:

import { GlideToPosition } from '@woven-canvas/plugin-canvas-controls'

editor.command(GlideToPosition, { centerX: 500, centerY: 300 })

For another camera control example, see:

• Using the Editor API

Vue Components

The Vue package provides the Hand tool for toolbar integration:

<script setup lang="ts">
import { WovenCanvas, HandTool, SelectTool, Toolbar } from '@woven-canvas/vue'
</script>

<template>
  <WovenCanvas>
    <template #toolbar>
      <Toolbar>
        <SelectTool />
        <HandTool />
      </Toolbar>
    </template>
  </WovenCanvas>
</template>

The Hand tool allows users to pan the canvas by clicking and dragging, without selecting blocks.