vant/packages/vant/src/image-preview

ImagePreview

Intro

Used to zoom in and preview the picture, and it supports two methods: function call and component call.

Install

Register component globally via app.use, refer to Component Registration for more registration ways.

import { createApp } from 'vue';
import { ImagePreview } from 'vant';

const app = createApp();
app.use(ImagePreview);

Function Call

Vant provides some utility functions that can quickly evoke global ImagePreview components.

For example, calling the showImagePreview function will render a Dialog directly in the page.

import { showImagePreview } from 'vant';

showImagePreview(['https://fastly.jsdelivr.net/npm/@vant/assets/apple-1.jpeg']);

Usage

Basic Usage

When calling showImagePreview, you can directly pass an array of images to display the image preview.

import { showImagePreview } from 'vant';

showImagePreview([
  'https://fastly.jsdelivr.net/npm/@vant/assets/apple-1.jpeg',
  'https://fastly.jsdelivr.net/npm/@vant/assets/apple-2.jpeg',
]);

Set Start Position

showImagePreview supports passing a configuration object, and you can specify the initial position (index value) of the image through the startPosition option.

import { showImagePreview } from 'vant';

showImagePreview({
  images: [
    'https://fastly.jsdelivr.net/npm/@vant/assets/apple-1.jpeg',
    'https://fastly.jsdelivr.net/npm/@vant/assets/apple-2.jpeg',
  ],
  startPosition: 1,
});

Show Close Icon

When the closeable option is enabled, a close icon will be displayed in the top-right corner of the popup layer. You can customize the icon by using the close-icon option, and the icon position can be customized using the close-icon-position option.

import { showImagePreview } from 'vant';

showImagePreview({
  images: [
    'https://fastly.jsdelivr.net/npm/@vant/assets/apple-1.jpeg',
    'https://fastly.jsdelivr.net/npm/@vant/assets/apple-2.jpeg',
  ],
  closeable: true,
});

Close Event

You can listen to the close event of the image preview through the onClose option.

import { showToast, showImagePreview } from 'vant';

showImagePreview({
  images: [
    'https://fastly.jsdelivr.net/npm/@vant/assets/apple-1.jpeg',
    'https://fastly.jsdelivr.net/npm/@vant/assets/apple-2.jpeg',
  ],
  onClose() {
    showToast('closed');
  },
});

Before Close

You can pass a callback function through the beforeClose option to perform specific operations before closing the image preview.

import { showImagePreview } from 'vant';

const instance = showImagePreview({
  images: [
    'https://fastly.jsdelivr.net/npm/@vant/assets/apple-1.jpeg',
    'https://fastly.jsdelivr.net/npm/@vant/assets/apple-2.jpeg',
  ],
  beforeClose: () => false,
});

setTimeout(() => {
  instance.close();
}, 2000);

Use ImagePreview Component

If you need to embed components or other custom content inside the ImagePreview, you can directly use the ImagePreview component and customize it using the index slot. Before using it, you need to register the component through app.use or other methods.

<van-image-preview v-model:show="show" :images="images" @change="onChange">
  <template v-slot:index>Page: {{ index + 1 }}</template>
</van-image-preview>

import { ref } from 'vue';

export default {
  setup() {
    const show = ref(false);
    const index = ref(0);
    const images = [
      'https://fastly.jsdelivr.net/npm/@vant/assets/apple-1.jpeg',
      'https://fastly.jsdelivr.net/npm/@vant/assets/apple-2.jpeg',
    ];
    const onChange = (newIndex) => {
      index.value = newIndex;
    };

    return {
      show,
      index,
      images,
      onChange,
    };
  },
};

Use image slot

When using ImagePreview component, you can custom the image through the image slot, such as render a video content. In this example, you can also set close-on-click-image prop to false, so that the preview won't be accidentally closed when you click on the video.

<van-image-preview
  v-model:show="show"
  :images="images"
  :close-on-click-image="false"
>
  <template #image="{ src }">
    <video style="width: 100%;" controls>
      <source :src="src" />
    </video>
  </template>
</van-image-preview>

import { ref } from 'vue';

export default {
  setup() {
    const show = ref(false);
    const images = [
      'https://www.w3school.com.cn/i/movie.ogg',
      'https://www.w3school.com.cn/i/movie.ogg',
      'https://www.w3school.com.cn/i/movie.ogg',
    ];
    return {
      show,
      images,
    };
  },
};

API

Methods

Vant exports following ImagePreview utility functions:

Methods	Description	Attribute	Return value
showImagePreview	Display a full-screen image preview component	string[] | ImagePreviewOptions	ImagePreview Instance

ImagePreviewOptions

Attribute	Description	Type	Default
images	Images URL list	string[]	[]
startPosition	Start position	number | string	0
showIndex	Whether to show index	boolean	true
showIndicators	Whether to show indicators	boolean	false
loop	Whether to enable loop	boolean	true
swipeDuration	Animation duration (ms)	number | string	300
onClose	Emitted when ImagePreview is closed	Function	-
onChange	Emitted when current image changed	Function	-
onScale	Emitted when scaling current image	Function	-
closeOnPopstate	Whether to close when popstate	boolean	true
doubleScale v4.7.2	Whether to enable double tap zoom gesture. When disabled, the image preview will be closed immediately upon clicking	boolean	true
closeOnClickImage v4.8.3	Whether to close when image is clicked	boolean	true
closeOnClickOverlay v4.6.4	Whether to close when overlay is clicked	boolean	true
vertical v4.8.6	Whether to enable vertical gesture sliding	boolean	false
beforeClose	Callback function before close	(action) => boolean | Promise	-
className	Custom className	string | Array | object	-
maxZoom	Max zoom	number | string	3
minZoom	Min zoom	number | string	1/3
closeable	Whether to show close icon	boolean	false
closeIcon	Close icon name	string	clear
closeIconPosition	Close icon position, can be set to top-left bottom-left bottom-right	string	top-right
transition	Transition, equivalent to name prop of transition	string	van-fade
overlayClass	Custom overlay class	string | Array | object	-
overlayStyle	Custom overlay style	object	-
teleport	Specifies a target element where ImagePreview will be mounted	string | Element	-

Props

Attribute	Description	Type	Default
v-model:show	Whether to show ImagePreview	boolean	false
images	Images URL list	string[]	[]
start-position	Start position	number | string	0
swipe-duration	Animation duration (ms)	number | string	300
show-index	Whether to show index	boolean	true
show-indicators	Whether to show indicators	boolean	false
loop	Whether to enable loop	boolean	true
double-scale	Whether to enable double tap zoom gesture. When disabled, the image preview will be closed immediately upon clicking	boolean	true
before-close	Callback function before close	(action: number) => boolean | Promise<boolean>	-
close-on-popstate	Whether to close when popstate	boolean	true
close-on-click-image v4.8.3	Whether to close when image is clicked	boolean	true
close-on-click-overlay v4.6.4	Whether to close when overlay is clicked	boolean	true
vertical v4.8.6	Whether to enable vertical gesture sliding	boolean	false
class-name	Custom className (apply to Popup in image preview)	string | Array | object	-
max-zoom	Max zoom	number | string	3
min-zoom	Min zoom	number | string	1/3
closeable	Whether to show close icon	boolean	false
close-icon	Close icon name	string	clear
close-icon-position	Close icon position, can be set to top-left bottom-left bottom-right	string	top-right
transition	Transition, equivalent to name prop of transition	string	van-fade
overlay-class	Custom overlay class	string | Array | object	-
overlay-style	Custom overlay style	object	-
teleport	Specifies a target element where ImagePreview will be mounted	string | Element	-

Events

Event	Description	Arguments
close	Emitted when closing ImagePreview	{ index: number, url: string }
closed	Emitted when ImagePreview is closed	-
change	Emitted when current image changed	index: number
scale	Emitted when scaling current image	{ index: number, scale: number }
long-press	Emitted when long press current image	{ index: number }

Methods

Use ref to get ImagePreview instance and call instance methods.

Name	Description	Attribute	Return value
resetScale 4.7.4	Reset the current image's zoom ratio	-	-
swipeTo	Swipe to target index	index: number, options?: SwipeToOptions	-

Types

The component exports the following type definitions:

import type {
  ImagePreviewProps,
  ImagePreviewOptions,
  ImagePreviewInstance,
  ImagePreviewScaleEventParams,
} from 'vant';

ImagePreviewInstance is the type of component instance:

import { ref } from 'vue';
import type { ImagePreviewInstance } from 'vant';

const imagePreviewRef = ref<ImagePreviewInstance>();

imagePreviewRef.value?.swipeTo(1);

Slots

Name	Description	SlotProps
index	Custom index	{ index: index of current image }
cover	Custom content that covers the image preview	-
image	Custom image content	{ src: current image src }

onClose Parameters

Attribute	Description	Type
url	URL of current image	number
index	Index of current image	number

onScale Parameters

Attribute	Description	Type
index	Index of current image	number
scale	scale of current image	number

Theming

CSS Variables

The component provides the following CSS variables, which can be used to customize styles. Please refer to ConfigProvider component.

Name	Default Value	Description
--van-image-preview-index-text-color	var(--van-white)	-
--van-image-preview-index-font-size	var(--van-font-size-md)	-
--van-image-preview-index-line-height	var(--van-line-height-md)	-
--van-image-preview-index-text-shadow	0 1px 1px var(--van-gray-8)	-
--van-image-preview-overlay-background	rgba(0, 0, 0, 0.9)	-
--van-image-preview-close-icon-size	22px	-
--van-image-preview-close-icon-color	var(--van-gray-5)	-
--van-image-preview-close-icon-margin	var(--van-padding-md)	-
--van-image-preview-close-icon-z-index	1	-