API

Suitable for scenarios such as opening a specified image array after a button click.

Playground

Playground

<script setup>
import { ref } from 'vue'
import { useViewer } 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', initialViewIndex: 0 })
const { show, isShown } = useViewer({ images, options })
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>
    <p>Images: {{ images.length }}</p>
    <p>{{ isShown ? 'Gallery open' : 'Ready to explore' }}</p>
  </main>
</template>

url: 'data-source' uses the image’s data-source attribute as the preview URL; initialViewIndex sets the starting image index (from 0).

Parameters and return values

useViewer({ images?, options? })

Parameter	Description
images	Image array, ref or getter for temporary galleries.
options	Viewer.js options, ref or getter.

Return value	Description
viewer	ShallowRef<ViewerJs | undefined>
isShown	Reactive modal visibility.
show(index?)	Open at an optional image index.
hide()	Close normally with the configured exit transition and hide / hidden callbacks; destroy the instance and remove temporary DOM after closing.
destroy()	Immediately destroy the instance and remove temporary DOM, without an exit transition or hide / hidden callbacks; show() can recreate it.

Call useViewer inside setup. It cleans up on scope disposal.

Closing or destroying the preview removes its temporary DOM. Changes to images or options during a preview apply the next time it opens. Calling show(index) again switches images within the current gallery.

Use viewer.value to call all Viewer.js methods. Viewer.js methods

Options

Pass these settings through options in useViewer({ images, options }). The API always opens in modal mode. inline is fixed to false and cannot be overridden.

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

Callbacks

Set callback functions such as viewed(event) in options. They correspond to Viewer.js events and receive the original DOM event, with operation data in event.detail. Click a name for its original documentation.

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.