simple-img-viewer

A simple and lightweight image viewer component for Vue 3, supporting zoom, rotation, keyboard navigation, image grouping, and thumbnail navigation.

中文文档请见这里。

Features

• 🖼️ 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

Installation

# npm
npm install simple-img-viewer

# yarn
yarn add simple-img-viewer

# pnpm
pnpm add simple-img-viewer

Usage

Basic Usage

1. 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')

2. Use the v-viewer directive 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>

Thumbnail Navigation

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

Advanced Configuration

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'
})

Detailed Usage Examples

1. Default Group Testing (Component Isolation)

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.

2. Custom Identifier Group Testing

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>

3. Nested Structure Testing

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>

4. Single Image Testing

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>

Options

| 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 |

Keyboard Shortcuts

• ← : Previous image
• → : Next image
• + : Zoom in
• - : Zoom out
• R : Rotate image
• ESC : Close viewer
• Click on thumbnails: Quick image switching

Development

# 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 lint

License

MIT

Author

Cee Vee X [email protected]

Repository

https://github.com/CeeVeeX/simple-img-viewer