Zoom & Pan Plugin
Relevant source files
The following files were used as context for generating this wiki page:
The Zoom & Pan plugin for vitepress-plugin-chartjs provides interactive capabilities for users to navigate data visualizations through mouse wheel scrolling, touch pinching, or click-and-drag selections. It leverages the underlying chartjs-plugin-zoom library to extend standard Chart.js functionality within a VitePress documentation environment.
Sources: example/plugins/zoom.md:3-5, README.md:14-15
Architecture and Lifecycle
The integration of the zoom feature follows a dual-stage process involving build-time configuration and client-side registration.
1. Build-Time Processing
During the build phase, the plugin's markdown renderer identifies chart or chartjs blocks. If the global enableZoom option is set to true in the VitePress configuration, the plugin automatically injects a default zoom and pan configuration into the chart's options object. This pre-computed configuration is then passed to the <VpChart /> component as a JSON string.
Sources: src/markdown/index.ts:145-164, src/markdown/index.ts:211-224
2. Client-Side Registration
Because Chart.js plugins interact with the DOM and window object, they must be registered in the client-side enhanceApp hook of the VitePress theme. This ensures SSR (Server-Side Rendering) compatibility.
The diagram above illustrates how the zoom functionality is prepared at build time but initialized only when the chart becomes visible in the browser.
Sources: src/markdown/index.ts:168-175, example/plugins/zoom.md:9-22, README.md:154-158
Configuration
Global Configuration
The plugin can be enabled for all charts globally via the VitePress configuration file.
| Option | Type | Default | Description |
|---|---|---|---|
enableZoom | boolean | false | When true, injects default wheel/pinch zoom and pan (mode: xy) into all charts. |
Sources: src/config.ts:153, example/api.md:46, src/markdown/index.ts:152-164
Per-Chart Configuration
Individual charts can override global settings or define specific zoom behaviors directly in their YAML/JSON markdown blocks.
options:
plugins:
zoom:
zoom:
wheel:
enabled: true
drag:
enabled: true
mode: x
pan:
enabled: true
mode: x
Sources: example/plugins/zoom.md:112-140, example/api.md:133-144
Feature Set
Zoom Methods
The plugin supports three primary interaction methods for zooming:
- Wheel Zoom: Users can zoom in and out using the mouse scroll wheel.
- Pinch Zoom: Supports touch gestures on mobile devices.
- Drag-to-Zoom: Users can draw a rectangle over a specific area to zoom into that selection.
| Interaction | Setting | Description |
|---|---|---|
| Wheel | zoom.wheel.enabled | Enables mouse wheel interaction. |
| Drag | zoom.drag.enabled | Enables area selection; requires backgroundColor and borderColor for the selection box. |
| Pinch | zoom.pinch.enabled | Enables touch-based zooming. |
Sources: example/plugins/zoom.md:112-126, src/markdown/index.ts:154-159
Axis Control
Zoom and pan operations can be restricted to specific axes using the mode property:
x: Horizontal navigation only.y: Vertical navigation only.xy: Full bidirectional navigation.
Sources: example/plugins/zoom.md:65-71, src/markdown/index.ts:157
Navigation Limits
To prevent users from navigating away from the data range, limits can be applied to both zoom and pan.
limits:
x:
min: 0
max: 100
minRange: 10
y:
min: original
max: original
Sources: example/plugins/zoom.md:144-152
Programmatic Control
The plugin provides utility functions for interacting with charts from external UI components (e.g., a "Reset" button).
| Function | Import Path | Description |
|---|---|---|
getChart(id) | vitepress-plugin-chartjs/client | Retrieves the Chart.js instance for a specific ID. |
resetZoom(id) | vitepress-plugin-chartjs/client | Resets the zoom and pan levels to the original state. |
Sources: example/plugins/zoom.md:156-168
Implementation Example
The following code demonstrates a scatter plot configured specifically for area selection (Drag-to-Zoom).
type: scatter
data:
datasets: [{ label: 'Points', data: [...] }]
options:
plugins:
zoom:
zoom:
drag:
enabled: true
backgroundColor: rgba(54, 162, 235, 0.3)
borderColor: rgba(54, 162, 235, 1)
borderWidth: 1
mode: xy
Sources: example/plugins/zoom.md:86-108
Summary
The Zoom & Pan Plugin offers a seamless way to add interactivity to static VitePress documentation. By combining build-time automated configuration with standard Chart.js plugin registration, it provides a high-performance, mobile-friendly navigation system for complex datasets.