v-viewer

Install v-viewer along with its peer dependency viewerjs using npm.

npm install v-viewer viewerjs

To use v-viewer directly in the browser via CDN, include the CSS for viewerjs, the Vue library, viewerjs, and the v-viewer UMD bundle.

<link href="//unpkg.com/viewerjs/dist/viewer.css" rel="stylesheet">
<script src="//unpkg.com/vue"></script>
<script src="//unpkg.com/viewerjs/dist/viewer.js"></script>
<script src="//unpkg.com/v-viewer/dist/index.umd.js"></script>
<script>
  app.use(VueViewer.default)
</script>

To use v-viewer globally, import it and the viewerjs CSS file, then call app.use() during application initialization. This installs the component, directive, and API globally.

import { createApp } from 'vue'
import App from './App.vue'
import 'viewerjs/dist/viewer.css'
import VueViewer from 'v-viewer'
const app = createApp(App)
app.use(VueViewer)
app.mount('#app')

Register the Viewer component locally or globally to wrap your images. You can use the images prop for an array of URLs or the trigger prop to react to changes in external HTML content.

<template>
  <!-- Using images prop -->
  <viewer :images="images" @inited="inited">
    <template #default="scope">
      <img v-for="src in scope.images" :key="src" :src="src">
    </template>
  </viewer>

  <!-- Using trigger prop for external HTML -->
  <viewer :trigger="externallyGeneratedHtmlWithImages">
    <div v-html="externallyGeneratedHtmlWithImages"/>
  </viewer>
</template>

<script lang="ts" setup>
import { component as Viewer } from "v-viewer"
import 'viewerjs/dist/viewer.css'

const images = ["https://picsum.photos/200/200"]
const inited = (viewer: any) => {
  // Access the viewer instance
}
</script>

Apply the v-viewer directive to a container element. All img elements within that container will be handled by the viewer. You can pass options directly to the directive.

<template>
  <!-- Basic usage -->
  <div class="images" v-viewer>
    <img v-for="src in images" :key="src" :src="src">
  </div>

  <!-- Usage with options -->
  <div class="images" v-viewer="{movable: false}">
    <img v-for="src in images" :src="src" :key="src">
  </div>
</template>

You can define global default options for the viewer during plugin installation using the defaultOptions key. This applies these settings to all instances created via the directive or component.

Additionally, you can update or reset these global defaults at any time using VueViewer.setDefaults().

// Setting defaults during installation
app.use(VueViewer, {
  defaultOptions: {
    zIndex: 9999
  }
})

// Resetting defaults globally at any time
import VueViewer from 'v-viewer'
VueViewer.setDefaults({
  zIndexInline: 2021,
})

When installing the v-viewer plugin, you can provide a name option to avoid naming conflicts with other plugins or components. The default name is viewer. If you change the name, you must use that new name for the directive, component, and API calls.

import { createApp } from 'vue'
import 'viewerjs/dist/viewer.css'
import VueViewer from 'v-viewer'
import App from './App.vue'

export const app = createApp(App)
app.use(VueViewer, {
  name: 'vuer',
  debug: true,
})
app.mount('#app')

To use v-viewer in your Vue application, use the install method. This registers the Viewer component, the v-viewer directive, and the $viewerApi global property.

By default, the plugin uses the name viewer. You can customize this name, enable debug mode, or set global default options for the underlying viewerjs engine.

The API allows you to show a gallery in modal mode without manually rendering img elements. This is useful for triggering a viewer from a button click.

• Options API: Access via this.$viewerApi({ options, images }) if installed globally via app.use().
• Composition API: Import api from v-viewer and call it directly.

// Composition API Example
import { api as viewerApi } from 'v-viewer'
import 'viewerjs/dist/viewer.css'

const images = [
  { src: 'https://picsum.photos/200/200', 'data-source': 'https://picsum.photos/800/800' }
]

const previewImgObject = () => {
  viewerApi({
    options: {
      toolbar: true,
      url: 'data-source',
      initialViewIndex: 1
    },
    images
  })
}

When calling app.use(vViewer, options), you can provide an InstallationOptions object:

• name (string, optional): The name used for the registered component and directive. Defaults to 'viewer'. If set to 'viewer', the global API property will be $viewerApi.
• debug (boolean, optional): Enables debug mode for the directive. Defaults to false.
• defaultOptions (Viewer.Options, optional): Global default options passed to Viewer.setDefaults for the underlying viewerjs library.

Props

• images (Array): An array of image sources.
• trigger (Object): An alternative to images. When trigger changes, the component re-renders the viewer.
• rebuild (Boolean, default: false): If true, the viewer instance is updated via the update method when source images change. Use this to resolve display issues during image updates.
• options (Object): Configuration options for the viewer.

Events

• inited: Emitted when the viewer is initialized. Returns the Viewer instance.