v-viewer

Image viewer component for vue, supports rotation, scale, zoom and so on, based on viewer.js

v-viewer for vue2

Live demo

Quick Example

• directive
• component
• api
• thumbnail & source
• viewer callback
• custom toolbar
• filter images
• change images

中文文档

Installation

Install from NPM

1npm install v-viewer viewerjs

Usage

To use v-viewer, simply import it and the css file, and call app.use() to install.

The component, directive and api will be installed together in the global.

Two different API styles are both supported: Options API and Composition API.

1import { createApp } from 'vue'
2import App from './App.vue'
3import 'viewerjs/dist/viewer.css'
4import VueViewer from 'v-viewer'
5const app = createApp(App)
6app.use(VueViewer)
7app.mount('#app')

1<template>
2  <div>
3    <!-- directive -->
4    <div class="images" v-viewer>
5      <img v-for="src in images" :key="src" :src="src">
6    </div>
7    <!-- component -->
8    <viewer :images="images">
9      <img v-for="src in images" :key="src" :src="src">
10    </viewer>
11    <!-- api -->
12    <button type="button" @click="show">Click to show</button>
13  </div>
14</template>
15<!-- Options API -->
16<script lang="ts">
17  import { defineComponent } from 'vue'
18  export default defineComponent({
19    data() {
20      return {
21        images: [
22          "https://picsum.photos/200/200",
23          "https://picsum.photos/300/200",
24          "https://picsum.photos/250/200"
25        ]
26      }
27    },
28    methods: {
29      show() {
30        this.$viewerApi({
31          images: this.images
32        })
33      }
34    }
35  })
36</script>
37<!-- Composition API -->
38<!-- <script lang="ts" setup>
39  import { api as viewerApi } from 'v-viewer'
40  const images = [
41    "https://picsum.photos/200/200",
42    "https://picsum.photos/300/200",
43    "https://picsum.photos/250/200"
44  ]
45  const show = () => {
46    viewerApi({
47      images
48    })
49  }
50</script> -->

Support UMD

Browser

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

CommonJS

1var VueViewer = require('VueViewer')

AMD

1require(['VueViewer'], function (VueViewer) {});

Usage of directive

Just add the directive v-viewer to any element, then all img elements in it will be handled by viewer.

You can set the options like this: v-viewer="{inline: true}"

Get the element by selector and then use el.$viewer to get the viewer instance if you need.

1<template>
2  <div>
3    <div class="images" v-viewer="{movable: false}">
4      <img v-for="src in images" :src="src" :key="src">
5    </div>
6    <button type="button" @click="show">Show</button>
7  </div>
8</template>
9<!-- Options API -->
10<script lang="ts">
11  import { defineComponent } from 'vue'
12  import 'viewerjs/dist/viewer.css'
13  import { directive as viewer } from "v-viewer"
14  export default defineComponent({
15    directives: {
16      viewer: viewer({
17        debug: true
18      })
19    },
20    data() {
21      return {
22        images: [
23          "https://picsum.photos/200/200",
24          "https://picsum.photos/300/200",
25          "https://picsum.photos/250/200"
26        ]
27      }
28    },
29    methods: {
30      show () {
31        const viewer = this.$el.querySelector('.images').$viewer
32        viewer.show()
33      }
34    }
35  })
36</script>
37<!-- Composition API -->
38<!-- <script lang="ts" setup>
39  import 'viewerjs/dist/viewer.css'
40  import { directive as viewer } from "v-viewer"
41  const vViewer = viewer({
42    debug: true
43  })
44  const images = [
45    "https://picsum.photos/200/200",
46    "https://picsum.photos/300/200",
47    "https://picsum.photos/250/200"
48  ]
49  const show = () => {
50    const viewer = document.querySelector('.images').$viewer
51    viewer.show()
52  }
53</script> -->

Directive modifiers

static

The viewer instance will be created only once after the directive binded.

If you're sure the images inside this element won't change again, use it to avoid unnecessary re-render.

1<div class="images" v-viewer.static="{inline: true}">
2  <img v-for="src in images" :src="src" :key="src">
3</div>

rebuild

The viewer instance will be updated by update method when the source images changed (added, removed or sorted) by default.

If you encounter any display problems, try rebuilding instead of updating.

1<div class="images" v-viewer.rebuild="{inline: true}">
2  <img v-for="src in images" :src="src" :key="src">
3</div>

Usage of component

You can simply import the component and register it locally too.

1<template>
2  <div>
3    <viewer :images="images"
4            @inited="inited"
5            class="viewer"
6            ref="viewer"
7            >
8      <template #default="scope">
9        <img v-for="src in scope.images" :src="src" :key="src">
10        {{scope.options}}
11      </template>
12    </viewer>
13    <button type="button" @click="show">Show</button>
14  </div>
15</template>
16<!-- Options API -->
17<script lang="ts">
18  import { defineComponent } from 'vue'
19  import 'viewerjs/dist/viewer.css'
20  import { component as Viewer } from "v-viewer"
21  export default defineComponent({
22    components: {
23      Viewer,
24    },
25    data() {
26      return {
27        images: [
28          "https://picsum.photos/200/200",
29          "https://picsum.photos/300/200",
30          "https://picsum.photos/250/200"
31        ]
32      }
33    },
34    methods: {
35      inited (viewer) {
36        this.$viewer = viewer
37      },
38      show () {
39        this.$viewer.show()
40      }
41    }
42  })
43</script>
44<!-- Composition API -->
45<!-- <script lang="ts" setup>
46  import 'viewerjs/dist/viewer.css'
47  import { component as Viewer } from "v-viewer"
48  const images = [
49    "https://picsum.photos/200/200",
50    "https://picsum.photos/300/200",
51    "https://picsum.photos/250/200"
52  ]
53  let $viewer:any = null
54  const inited = (viewer) => {
55    $viewer = viewer
56  }
57  const show = () => {
58    $viewer.show()
59  }
60</script> -->

Component props

images

• Type: Array

trigger

• Type: Object

You can replace images with trigger, to accept any type of prop. when the trigger changes, the component will re-render the viewer.

1<viewer :trigger="externallyGeneratedHtmlWithImages">
2  <div v-html="externallyGeneratedHtmlWithImages"/>
3</viewer>

rebuild

• Type: Boolean
• Default: false

The viewer instance will be updated by update method when the source images changed (added, removed or sorted) by default.

If you encounter any display problems, try rebuilding instead of updating.

1<viewer
2  ref="viewer"
3  :options="options"
4  :images="images"
5  rebuild
6  class="viewer"
7  @inited="inited"
8>
9  <template #default="scope">
10    <img v-for="src in scope.images" :src="src" :key="src">
11    {{scope.options}}
12  </template>
13</viewer>

Component events

inited

• viewer: Viewer

Listen for the inited event to get the viewer instance, or use this.refs.xxx.$viewer.

Usage of api

Only available in modal mode.

You can call the function: this.$viewerApi({options: {}, images: []}) to show gallery without rendering the img elements yourself.

The function returns the current viewer instance.

1<template>
2  <div>
3    <button type="button" class="button" @click="previewURL">URL Array</button>
4    <button type="button" class="button" @click="previewImgObject">Img-Object Array</button>
5  </div>
6</template>
7<!-- Options API -->
8<script lang="ts">
9  import { defineComponent } from 'vue'
10  import 'viewerjs/dist/viewer.css'
11  import { api as viewerApi } from "v-viewer"
12  export default defineComponent({
13    data() {
14      return {
15        sourceImageURLs: [
16          'https://picsum.photos/200/200?random=1',
17          'https://picsum.photos/200/200?random=2'
18        ],
19        sourceImageObjects: [
20          {
21            'src': 'https://picsum.photos/200/200?random=3',
22            'data-source': 'https://picsum.photos/800/800?random=3'
23          },
24          {
25            'src': 'https://picsum.photos/200/200?random=4',
26            'data-source': 'https://picsum.photos/800/800?random=4'
27          }
28        ]
29      }
30    },
31    methods: {
32      previewURL () {
33        // If you use the `app.use` full installation, you can use `this.$viewerApi` directly like this
34        const $viewer = this.$viewerApi({
35          images: this.sourceImageURLs
36        })
37      },
38      previewImgObject () {
39        // Or you can just import the api method and call it.
40        const $viewer = viewerApi({
41          options: {
42            toolbar: true,
43            url: 'data-source',
44            initialViewIndex: 1
45          },
46          images: this.sourceImageObjects
47        })
48      }
49    }
50  })
51</script>
52<!-- Composition API -->
53<!-- <script lang="ts" setup>
54import 'viewerjs/dist/viewer.css'
55import { api as viewerApi } from 'v-viewer'
56const sourceImageURLs = [
57  'https://picsum.photos/200/200?random=1',
58  'https://picsum.photos/200/200?random=2'
59]
60const sourceImageObjects = [
61  {
62    src: 'https://picsum.photos/200/200?random=3',
63    'data-source': 'https://picsum.photos/800/800?random=3'
64  },
65  {
66    src: 'https://picsum.photos/200/200?random=4',
67    'data-source': 'https://picsum.photos/800/800?random=4'
68  }
69]
70const previewURL = () => {
71  // If you use the `app.use` full installation, you can use `this.$viewerApi` directly like this
72  const $viewer = this.$viewerApi({
73    images: sourceImageURLs
74  })
75}
76const previewImgObject = () => {
77  // Or you can just import the api method and call it.
78  const $viewer = viewerApi({
79    options: {
80      toolbar: true,
81      url: 'data-source',
82      initialViewIndex: 1
83    },
84    images: sourceImageObjects
85  })
86}
87</script> -->

Options & Methods of Viewer

Refer to viewer.js.

Plugin options

name

• Type: String
• Default: viewer

If you need to avoid name conflict, you can import it like this:

1import { createApp } from 'vue'
2import 'viewerjs/dist/viewer.css'
3import VueViewer from 'v-viewer'
4import App from './App.vue'
5
6export const app = createApp(App)
7app.use(VueViewer, {
8  name: 'vuer',
9  debug: true,
10})
11app.mount('#app')
12

1<template>
2<div>
3  <!-- directive name -->
4  <div class="images" v-vuer="{movable: false}">
5    <img v-for="src in images" :src="src" :key="src">
6  </div>
7  <button type="button" @click="show">Show</button>
8  <!-- component name -->
9  <vuer :images="images">
10    <img v-for="src in images" :src="src" :key="src">
11  </vuer>
12  </div>
13</template>
14<!-- Options API -->
15<script lang="ts">
16  import { defineComponent } from 'vue'
17  export default defineComponent({
18    data() {
19      return {
20        images: [
21          "https://picsum.photos/200/200",
22          "https://picsum.photos/300/200",
23          "https://picsum.photos/250/200"
24        ]
25      };
26    },
27    methods: {
28      show () {
29        // viewerjs instance name
30        const vuer = this.$el.querySelector('.images').$vuer
31        vuer.show()
32        // api name
33        this.$vuerApi({
34          images: this.images
35        })
36      }
37    }
38  })
39</script>
40<!-- Composition API -->
41<script lang="ts" setup>
42  import { api as vuerApi } from 'v-viewer'
43  const images = [
44    "https://picsum.photos/200/200",
45    "https://picsum.photos/300/200",
46    "https://picsum.photos/250/200"
47  ]
48  const show = () => {
49    // viewerjs instance name
50    const vuer = document.querySelector('.images').$vuer
51    vuer.show()
52    // api name
53    vuerApi({
54      images
55    })
56  }
57</script>

defaultOptions

• Type: Object
• Default: undefined

If you need to set the viewer default options, you can import it like this:

1import { createApp } from 'vue'
2import 'viewerjs/dist/viewer.css'
3import VueViewer from 'v-viewer'
4import App from './App.vue'
5
6export const app = createApp(App)
7app.use(VueViewer, {
8  defaultOptions: {
9    zIndex: 9999
10  }
11})
12app.mount('#app')

And you can reset the default options at any other time:

1import VueViewer from 'v-viewer'
2
3VueViewer.setDefaults({
4  zIndexInline: 2021,
5})