A simple and lightweight image viewer component for Vue 3, supporting zoom, rotation, keyboard navigation, image grouping, and thumbnail navigation.
中文文档请见这里。
- 🖼️ Image preview with zoom and rotation
- ⌨️ Keyboard navigation (arrow keys, ESC, +, -, R)
- 🔖 Image grouping by identifiers
- 🖼️ Thumbnail navigation for quick image switching
- 📱 Responsive design
- 📦 Lazy loading support
- 🔄 Component isolation (different components have separate image groups)
- 🎨 Customizable styles
# npm
npm install simple-img-viewer
# yarn
yarn add simple-img-viewer
# pnpm
pnpm add simple-img-viewer- Import and register the plugin in your Vue app:
import viewer from 'simple-img-viewer'
import { createApp } from 'vue'
import App from './App.vue'
import 'simple-img-viewer/dist/index.css'
const app = createApp(App)
app.use(viewer)
app.mount('#app')- Use the
v-viewerdirective in your components:
<template>
<!-- Default group -->
<div v-viewer>
<img src="image1.jpg" alt="Image 1">
<img src="image2.jpg" alt="Image 2">
</div>
<!-- Custom group -->
<div v-viewer="'animals'">
<img src="cat.jpg" alt="Cat">
<img src="dog.jpg" alt="Dog">
</div>
<!-- Single image -->
<img v-viewer src="single.jpg" alt="Single image">
</template>The viewer automatically generates thumbnails for image groups, allowing quick navigation between images:
- Thumbnails are displayed at the bottom of the preview dialog
- Clicking a thumbnail switches directly to that image
- The active image's thumbnail is highlighted
- Thumbnails use the same image source as the main images for consistency
You can pass options when installing the plugin:
app.use(viewer, {
defaultIdentifier: 'my-default-group',
zIndex: 1000,
keyboard: true,
zoomable: true,
rotatable: true,
lazyLoad: true,
cssPath: '/custom-viewer.css'
})By default, images without a specific group identifier are included in the default group, and default groups in different components are isolated from each other.
Parent component default group:
<template>
<!-- Parent component default group -->
<div v-viewer class="img-container">
<div class="img-item">
<img src="https://picsum.photos/id/1/400/300" alt="Nature scene 1">
</div>
<div class="img-item">
<img src="https://picsum.photos/id/2/400/300" alt="Nature scene 2">
</div>
</div>
</template>Child component (ChildComponent.vue) default group:
<template>
<div v-viewer class="img-container">
<div class="img-item">
<img src="https://picsum.photos/id/10/400/300" alt="Child component image 1">
</div>
<div class="img-item">
<img src="https://picsum.photos/id/11/400/300" alt="Child component image 2">
</div>
</div>
</template>Parent and child component default groups are independent - previewing images won't affect each other.
By specifying an identifier for the v-viewer directive, you can group images, and images with the same identifier will be linked in the preview.
<template>
<!-- Animals group (identifier: "animals") -->
<div v-viewer="'animals'" class="img-container">
<div class="img-item">
<img data-viewer="animals" src="https://picsum.photos/id/20/400/300" alt="Animal 1">
</div>
<div class="img-item">
<img data-viewer="animals" src="https://picsum.photos/id/21/400/300" alt="Animal 2">
</div>
</div>
<!-- Cities group (identifier: "cities") -->
<div v-viewer="'cities'" class="img-container">
<div class="img-item">
<img data-viewer="cities" src="https://picsum.photos/id/40/400/300" alt="City 1">
</div>
<div class="img-item">
<img data-viewer="cities" src="https://picsum.photos/id/41/400/300" alt="City 2">
</div>
</div>
</template>Images in deeply nested DOM structures will still be correctly identified and grouped if they have the same identifier.
<template>
<div v-viewer="'nested'" class="container">
<div class="layer-1">
<div class="layer-2">
<div class="img-item">
<img data-viewer="nested" src="https://picsum.photos/id/60/400/300" alt="Nested image 1">
</div>
</div>
<div class="layer-2">
<div class="img-item">
<img data-viewer="nested" src="https://picsum.photos/id/61/400/300" alt="Nested image 2">
</div>
</div>
</div>
</div>
</template>Using the v-viewer directive directly on a single <img> tag enables preview functionality for that image, with navigation buttons automatically disabled.
<template>
<div class="img-container">
<div class="img-item">
<img v-viewer src="https://picsum.photos/id/80/600/400" alt="Single image 1">
</div>
<div class="img-item">
<img v-viewer src="https://picsum.photos/id/81/600/400" alt="Single image 2">
</div>
</div>
</template>| Option | Type | Default | Description |
|---|---|---|---|
defaultIdentifier |
string | 'default-viewer-group' | Default group identifier for images without a specific group |
dialogClass |
string | '' | Custom CSS class for the viewer dialog |
zIndex |
number | 1000 | Z-index value for the viewer dialog |
keyboard |
boolean | true | Enable/disable keyboard navigation |
zoomable |
boolean | true | Enable/disable image zooming |
rotatable |
boolean | true | Enable/disable image rotation |
lazyLoad |
boolean | true | Enable/disable lazy loading of images |
cssPath |
string | 'viewer.css' | Path to custom CSS file for styling the viewer |
←: Previous image→: Next image+: Zoom in-: Zoom outR: Rotate imageESC: Close viewer- Click on thumbnails: Quick image switching
# Clone the repository
git clone https://github.com/CeeVeeX/simple-img-viewer.git
# Install dependencies
pnpm install
# Run development server
pnpm dev
# Build the package
pnpm build
# Run linting
pnpm lintCee Vee X ceeveex@hotmail.com