Directive

Suitable for simple image browsing without complex customization, while also supporting images in dynamically rendered Markdown or HTML whose content is not known in advance. By default, it watches additions, removals and attribute changes of <img> elements inside the element the directive is bound to and automatically updates the gallery.

Playground

vue

<script setup>
import { ref } from 'vue'
import { vViewer } from 'v-viewer'
const sourceImages = [
  '/images/photo-01.jpg',
  '/images/photo-02.jpg',
  '/images/photo-03.jpg',
  '/images/photo-04.jpg',
  '/images/photo-05.jpg',
  '/images/photo-06.jpg',
  '/images/photo-07.jpg',
  '/images/photo-08.jpg',
  '/images/photo-09.jpg',
  '/images/photo-10.jpg',
].map((original) => ({
  src: original.replace('/images/', '/images/thumbnails/'),
  'data-source': original,
}))
const images = ref(sourceImages.slice(0, 5))
const options = ref({ toolbar: true, url: 'data-source' })
function onViewed(event) {
  console.log(event.detail.index)
}
const gallery = ref(null)
function show() {
  gallery.value.$viewer.show()
}
function add() {
  images.value.push(sourceImages[images.value.length])
}
function remove() {
  images.value.pop()
}
</script>

<template>
  <main class="viewer-example">
    <div class="controls">
      <button :disabled="images.length === sourceImages.length" @click="add">
        Add image
      </button>
      <button :disabled="images.length === 0" @click="remove">
        Remove image
      </button>
      <button class="open" :disabled="images.length === 0" @click="show()">
        Show viewer
      </button>
      <div class="toolbar" role="group" aria-label="Toggle toolbar">
        <span>Toggle toolbar</span>
        <button
          :aria-pressed="options.toolbar ? 'true' : 'false'"
          @click="options.toolbar = true"
        >
          On
        </button>
        <button
          :aria-pressed="options.toolbar ? 'false' : 'true'"
          @click="options.toolbar = false"
        >
          Off
        </button>
      </div>
    </div>
    <div ref="gallery" v-viewer="options" @viewed="onViewed" class="gallery">
      <img
        v-for="(image, index) in images"
        :key="image.src"
        :src="image.src"
        :data-source="image['data-source']"
        :alt="`Landscape ${index + 1}`"
      />
    </div>
  </main>
</template>

Rendered HTML works the same way:

vue

<article v-viewer v-html="html" />

Binding and modifiers

Binding	Description
v-viewer="options"	Accepts Viewer.js options. Deep changes rebuild the instance.
`v-viewer="{ observe: false }"`	Disable automatic image DOM updates.
`v-viewer="{ observe: 100 }"`	Batch image DOM changes in a 100ms window; default `true` uses 50ms, `0` adds no batching delay.
`v-viewer="{ rebuild: true }"`	Recreate the instance when images change; defaults to `false` and supports reactive changes.
`.rebuild`	Shorthand for `rebuild: true`.

rebuild in the binding takes precedence over .rebuild, including an explicit false. When omitted or undefined, the modifier applies.

By default, additions, removals and attribute changes of <img> elements inside the element the directive is bound to automatically update the gallery. Access the instance as element.$viewer. Unmounting disconnects the observer and destroys the instance.

See automatic updates with observe for values, update timing and usage guidance.

import type { ViewerElement } from 'v-viewer'
const element = document.querySelector<ViewerElement>('#gallery')
element?.$viewer?.show()

Options

Pass these settings directly in the object bound to v-viewer="options". Deep changes rebuild the instance.

These match Viewer.js options. Each name links to its original documentation; available settings and defaults depend on the installed Viewer.js version.

Prop	Type	Purpose
`backdrop`	boolean / string	Control the modal backdrop; `static` keeps clicks on it from closing the viewer.
`button`	boolean	Show the button in the upper-right corner.
`className`	string	Add custom classes to the viewer root.
`container`	string / Element	Choose the modal container using an element or CSS selector.
`filter`	function	Include images for which the filter returns `true`; exclude the others.
`fullscreen`	boolean / FullscreenOptions	Request browser fullscreen during playback, optionally with Fullscreen API settings.
`focus`	boolean	Focus the active thumbnail on initialization; requires `keyboard`.
`inheritedAttributes`	array	Choose additional source-image attributes to copy; `src` and `alt` are always copied.
`initialCoverage`	number	Set the initial image coverage, greater than 0 and at most 1.
`initialViewIndex`	number	Choose the starting image index, also used when `view()` receives no index.
`inline`	boolean	Display the viewer inline when enabled, or in modal mode when disabled.
`autoplay`	boolean	Advance slides automatically during playback.
`interval`	number	Set the delay between slides in milliseconds.
`keyboard`	boolean	Allow keyboard controls.
`loading`	boolean	Display a loading indicator while fetching an image.
`loop`	boolean	Wrap image navigation between the first and last images.
`magnifier`	boolean / object	Show a hover magnifier in fullscreen view, with configurable size, ratio and opacity; unavailable on touch screens.
`maxZoomRatio`	number / function	Limit magnification with a ratio or a function of the image and its data.
`minHeight`	number	Set the minimum inline viewer height in pixels.
`minWidth`	number	Set the minimum inline viewer width in pixels.
`minZoomRatio`	number / function	Limit reduction with a ratio or a function of the image and its data.
`movable`	boolean	Allow image movement.
`navbar`	boolean / number / string / object	Configure thumbnail visibility, size and position, with further layout settings in object form.
`navigation`	boolean / number / object	Configure the side navigation buttons, including individual visibility and size.
`preload`	boolean	Load adjacent images before they are viewed.
`rotatable`	boolean	Allow image rotation.
`rotateOnGesture`	boolean	Rotate through gesture events, such as two-finger gestures in Mac Safari.
`rotateOnTouch`	boolean	Rotate with two fingers on a touch screen.
`scalable`	boolean	Allow axis scaling, including horizontal and vertical flips.
`slideOnTouch`	boolean	Navigate between images with touch swipes.
`slideOnWheel`	boolean / string	Navigate with the wheel, optionally requiring modifier keys; applies over thumbnails or when wheel zoom does not handle the event.
`title`	boolean / number / function / array	Configure title visibility and content; the default uses `alt` or the filename from the URL.
`toggleOnDblclick`	boolean	Switch between natural and initial image sizes on double-click.
`toolbar`	boolean / number / object	Configure toolbar placement and button visibility, size and click behavior.
`tooltip`	boolean	Display the current zoom percentage while zooming.
`transition`	boolean / object	Enable CSS transitions, or disable selected action transitions using an object.
`url`	string / function	Read the full image URL from a named image attribute or a function result.
`zIndex`	number	Set the modal viewer’s CSS stacking order.
`zIndexInline`	number	Set the inline viewer’s CSS stacking order.
`zoomOnGesture`	boolean	Zoom through gesture events, such as pinch gestures in Mac Safari.
`zoomOnTouch`	boolean	Zoom through dragging gestures on a touch screen.
`zoomOnWheel`	boolean / string	Zoom with the wheel, optionally requiring one or more modifier keys.
`zoomRatio`	number	Set the ratio increment for wheel zoom.
`zoomable`	boolean	Allow image zooming.

Events

Viewer.js dispatches native DOM events on the HTML element bound to the directive. Listen using syntax such as @viewed. The handler receives the original event, with operation data in event.detail. Use @show.prevent to cancel opening.

vue

<div v-viewer="options" @viewed="onViewed">
  <img src="/images/photo-01.jpg" />
</div>

Name	When it fires / useful data
`ready`	The viewer UI is initialized. In modal mode this can happen on the first opening.
`show` / `shown`	Before opening / after the opening transition completes in modal mode.
`hide` / `hidden`	Before closing / after the closing transition completes in modal mode.
`view` / `viewed`	Before displaying an image / after it is displayed. `detail.index` is zero-based; `image` and `originalImage` identify the preview and source images.
`move` / `moved`	Before / after moving. `detail.x`, `y`, `oldX` and `oldY` describe the position change.
`rotate` / `rotated`	Before / after rotation. `detail.degree` and `oldDegree` describe the angle change.
`scale` / `scaled`	Before / after scaling or flipping. `detail.scaleX`, `scaleY`, `oldScaleX` and `oldScaleY` describe the change.
`zoom` / `zoomed`	Before / after zooming. `detail.ratio` and `oldRatio` contain the zoom ratios.
`play` / `stop`	Before starting / stopping a slideshow.
`playing`	Before showing each slide during playback.

Callbacks

You can also set Viewer.js callbacks in options, using the names and parameters listed above:

const options = {
  viewed(event) {
    console.log(event.detail.index)
  },
}

When @viewed and options.viewed are both supplied, both run for the same event. Use either when they perform the same work.

Migrating from older versions

The .static modifier has been removed; replace it with { observe: false }.

Directive ​

Playground ​

Binding and modifiers ​

Options ​

Events ​

Callbacks ​

Migrating from older versions ​