VitePress Image Preview

A lightweight image preview plugin for VitePress that provides modal-based image viewing with zoom, pan, copy, and download functionality.

Features

• 🔍 Image Preview Modal - Click images in your documentation to open an interactive preview
• 🔎 Zoom Control - Zoom in/out with mouse wheel or buttons (0.5x - 3.0x)
• 🖱️ Pan & Drag - Drag enlarged images to view different areas
• 📋 Copy URL - Copy image URL to clipboard with visual feedback
• ⬇️ Download - Direct image download with automatic filename detection
• ⌨️ Keyboard Navigation - Full keyboard support (Esc, +/-, Tab, arrows)
• 📱 Responsive - Mobile-optimized with touch support
• ♿ Accessible - WCAG 2.1 compliant with focus management and screen reader support

Installation

npm

npm install @cybertramp/vitepress-image-preview

yarn

yarn add @cybertramp/vitepress-image-preview

bun

bun add @cybertramp/vitepress-image-preview
# OR
bun add github:cybertramp/vitepress-image-preview

Usage

Update your VitePress theme configuration file (theme/index.ts):

import DefaultTheme from "vitepress/theme";
import { withImagePreview } from "@cybertramp/vitepress-image-preview";
import "@cybertramp/vitepress-image-preview/style.css";

export default withImagePreview(DefaultTheme, {
  selector: ".vp-doc img",    // CSS selector for previewable images
  initialScale: 1,            // Initial zoom level when modal opens
  zoomStep: 0.25,             // Zoom increment for buttons/wheel
  minScale: 0.5,              // Minimum zoom level
  maxScale: 3,                // Maximum zoom level
  closeOnBackdrop: true,      // Close modal when clicking backdrop
});

Configuration

| Option | Type | Default | Description | |--------|------|---------|-------------| | selector | string | .vp-doc img | CSS selector for images to preview | | initialScale | number | 1 | Initial zoom level (1 = 100%) | | zoomStep | number | 0.25 | Zoom increment per action | | minScale | number | 0.5 | Minimum allowed zoom (0.5 = 50%) | | maxScale | number | 3 | Maximum allowed zoom (3 = 300%) | | closeOnBackdrop | boolean | true | Close modal on backdrop click |

Excluding Images

To exclude specific images from preview functionality, add either attribute or class:

<!-- Using data attribute -->
<img src="/logo.svg" alt="Logo" data-no-image-preview>

<!-- Using class on parent -->
<a class="no-image-preview" href="/original.png">
  <img src="/thumbnail.png" alt="Thumbnail">
</a>

Controls

Keyboard Shortcuts

| Key | Action | |-----|--------| | Esc | Close preview | | + / = | Zoom in | | - | Zoom out | | Tab | Navigate controls | | Shift + Tab | Navigate controls (reverse) |

Mouse

| Action | Behavior | |--------|----------| | Scroll wheel | Zoom in/out | | Drag (zoomed) | Pan image | | Click backdrop | Close (if enabled) |

Project Structure

src/
├── index.ts       # Vue component + theme wrapper
└── style.css      # Modal styles and animations

Development

Install Dependencies

bun install

Build

bun run build

Type declarations and CSS are automatically included in the bundle.

Preview Demo

bun run demo

Opens a local VitePress dev server at http://localhost:5173.

Build Static Demo

bun run demo:build

Preview Built Demo

bun run demo:preview

Technical Details

• Type: ES Module with TypeScript declarations
• Peer Dependencies: vue >= 3.3.0, vitepress >= 1.0.0
• Build: TypeScript + Vite
• CSS: Scoped to plugin, separate import to avoid bundle duplication
• Bundle Size: Minimal (render functions only, no unnecessary abstractions)

Browser Support

Modern browsers with support for:

• ES2022
• CSS Grid & Flexbox
• ResizeObserver
• Clipboard API (with fallback)
• Pointer Events

License

MIT

Developed for VitePress documentation sites.