Van Image Preview

Vant ImagePreview Component

Used to zoom in and preview images, supporting both function call and component usage.

When to Invoke

Invoke this skill when:

• User needs to implement image preview functionality
• User wants to create image galleries or photo viewers
• User needs zoom and swipe gestures for images
• User wants to preview images with custom content
• User asks about programmatic image preview control

Features

• Function Call: Quick invocation via showImagePreview function
• Component Usage: Full component control with slots
• Zoom Support: Pinch-to-zoom and double-tap zoom
• Swipe Navigation: Swipe between multiple images
• Custom Content: Support custom index and image slots
• Close Control: Configurable close behavior
• Event Callbacks: Multiple events for interaction handling

API Reference

Methods

ImagePreviewOptions

Props (Component Usage)

Events

Methods (Component)

Slots

Types

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

Usage Examples

Basic Usage (Function Call)

<template>
  <van-button @click="showPreview">Show Preview</van-button>
</template>

<script setup>
import { showImagePreview } from 'vant';

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

Set Start Position

<template>
  <van-button @click="showPreview">Show Preview</van-button>
</template>

<script setup>
import { showImagePreview } from 'vant';

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

Show Close Icon

<template>
  <van-button @click="showPreview">Show Preview</van-button>
</template>

<script setup>
import { showImagePreview } from 'vant';

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

Close Event

<template>
  <van-button @click="showPreview">Show Preview</van-button>
</template>

<script setup>
import { showToast, showImagePreview } from 'vant';

const showPreview = () => {
  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');
    },
  });
};
</script>

Before Close

<template>
  <van-button @click="showPreview">Show Preview</van-button>
</template>

<script setup>
import { showImagePreview } from 'vant';

const showPreview = () => {
  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);
};
</script>

Component Usage

<template>
  <van-button @click="show = true">Show Preview</van-button>
  <van-image-preview v-model:show="show" :images="images" @change="onChange">
    <template #index>Page: {{ index + 1 }}</template>
  </van-image-preview>
</template>

<script setup>
import { ref } from 'vue';

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 => {
  index.value = newIndex;
};
</script>

Custom Image Slot (Video)

<template>
  <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>
</template>

<script setup>
import { ref } from 'vue';

const show = ref(false);
const images = [
  'https://www.w3school.com.cn/i/movie.ogg',
  'https://www.w3school.com.cn/i/movie.ogg',
];
</script>

Common Issues

1. Images Not Loading

Ensure image URLs are accessible and properly formatted:

showImagePreview({
  images: ['https://example.com/image.jpg'],
});

2. Programmatic Close

Use the instance returned by showImagePreview:

const instance = showImagePreview({ images: [...] });
instance.close();

3. Custom Index Display

Use the index slot for custom formatting:

<van-image-preview v-model:show="show" :images="images">
  <template #index="{ index }">
    {{ index + 1 }} / {{ images.length }}
  </template>
</van-image-preview>

Component Interactions

With Image Grid

<template>
  <van-grid :column-num="3">
    <van-grid-item 
      v-for="(image, index) in images" 
      :key="index"
      @click="showPreview(index)"
    >
      <van-image :src="image" />
    </van-grid-item>
  </van-grid>
</template>

<script setup>
import { ref } from 'vue';
import { showImagePreview } from 'vant';

const images = ref([
  'https://fastly.jsdelivr.net/npm/@vant/assets/apple-1.jpeg',
  'https://fastly.jsdelivr.net/npm/@vant/assets/apple-2.jpeg',
  'https://fastly.jsdelivr.net/npm/@vant/assets/apple-3.jpeg',
]);

const showPreview = (startPosition) => {
  showImagePreview({
    images: images.value,
    startPosition,
  });
};
</script>

With Long Press

<template>
  <van-button @click="showPreview">Show Preview</van-button>
</template>

<script setup>
import { showImagePreview, showToast } from 'vant';

const showPreview = () => {
  showImagePreview({
    images: ['https://fastly.jsdelivr.net/npm/@vant/assets/apple-1.jpeg'],
    onLongPress: ({ index }) => {
      showToast('Long pressed');
    },
  });
};
</script>

Best Practices

1. Optimize images: Use appropriately sized images for better performance
2. Provide close option: Always provide a way to close the preview
3. Handle errors: Handle image loading errors gracefully
4. Accessibility: Ensure preview is accessible with keyboard navigation
5. Mobile gestures: Test zoom and swipe gestures on mobile devices