ImagePreview - Vant 4
ImagePreview
🖼️ Transform your images into immersive, full-screen experiences! Give your users the power to explore every detail with smooth zooming, elegant transitions, and intuitive gestures. Perfect for galleries, product showcases, and any visual content that deserves the spotlight.
🎯 Intro
Welcome to the ultimate image viewing experience! Our ImagePreview component brings professional-grade image browsing to your Vue applications. Whether you need quick function calls for instant previews or full component integration for custom experiences, we've got you covered. Zoom, swipe, and explore images like never before! ✨
📦 Install
Ready to elevate your image viewing experience? Getting started is incredibly simple! Register the ImagePreview component globally via app.use and unlock powerful image preview capabilities throughout your application. Check out our Component Registration guide for alternative setup methods.
import { createApp } from'vue'; import { ImagePreview } from'vant'; const app = createApp(); app.use(ImagePreview);⚡ Function Call
Experience the magic of instant image previews! Vant provides powerful utility functions that can instantly summon beautiful, full-screen image galleries with just a single line of code.
For example, calling the showImagePreview function will render a stunning image preview directly on your page - no complex setup required!
import { showImagePreview } from'vant'; showImagePreview(['https://fastly.jsdelivr.net/npm/@vant/assets/apple-1.jpeg']);🎨 Usage
🌟 Basic Usage
Creating stunning image galleries has never been easier! When calling showImagePreview, simply pass an array of image URLs and watch as your images transform into an immersive, swipeable gallery experience.
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
Take control of your user's journey! showImagePreview supports advanced configuration options, allowing you to specify exactly which image should be displayed first through the startPosition option. Perfect for highlighting specific content or continuing from where users left off.
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
Give users complete control over their viewing experience! Enable the closeable option to display an elegant close icon in the top-right corner. Customize the icon style with close-icon and position it perfectly using close-icon-position - because every detail matters in great UX design!
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
Stay connected with your users' actions! Listen to the close event through the onClose option and trigger custom behaviors, analytics, or feedback. Perfect for tracking user engagement or providing contextual responses.
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
Take control of the closing process! Use the beforeClose callback to perform validation, save user progress, or show confirmation dialogs before the preview closes. This powerful feature ensures users never lose their place unexpectedly.
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
Unlock unlimited customization possibilities! When you need to embed custom components, overlays, or interactive elements inside the ImagePreview, use the component approach with powerful slot customization. The index slot gives you complete creative freedom to design unique viewing experiences.
import { ref } from'vue'; exportdefault { 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', ]; constonChange = (newIndex) => { index.value = newIndex; }; return { show, index, images, onChange, }; }, };🎬 Use Image Slot
Break free from traditional image constraints! The image slot opens up a world of possibilities - display videos, interactive content, or any custom media you can imagine. Set close-on-click-image to false for interactive content to prevent accidental closures and create truly engaging experiences.
import { ref } from'vue'; exportdefault { 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, }; }, };When you customize the image through the image slot, you can bind the style and onLoad callback through the params of the slot, which can allow the <img> tag to support image scaling.
🔧 API
⚙️ Methods
Vant exports powerful ImagePreview utility functions to give you complete programmatic control:
| Name | Description | Attribute | Return value |
|---|---|---|---|
| showImagePreview | Show image preview | options | string[] | imagePreview instance |
🎛️ ImagePreviewOptions
Configure every aspect of your image preview experience with these comprehensive options:
| Attribute | Description | Type | Default |
|---|---|---|---|
| images | Images URL list | string[] | [] |
| startPosition | Start position | number | string | 0 |
| swipeDuration | Animation duration (ms) | number | string | 300 |
| showIndex | Whether to show index | boolean | true |
| showIndicators | Whether to show indicators | boolean | false |
| loop | Whether to enable loop | boolean | true |
| onClose | Triggered when closing | Function | - |
| onScale | Triggered when scaling | Function | - |
| beforeClose | Callback function before close | Function | - |
| closeable | Whether to show close icon | boolean | false |
| closeIcon | Close icon name | string | clear |
| closeIconPosition | Close icon position | 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 | - |
| maxZoom | Max zoom | number | string | 3 |
| minZoom | Min zoom | number | string | 1/3 |
| closeOnClickImage | Whether to close when clicking image | boolean | true |
| closeOnClickOverlay | Whether to close when clicking overlay | boolean | true |
| vertical | Whether to enable vertical gesture | boolean | false |
🎯 Props
Fine-tune your ImagePreview component with these powerful properties:
| Attribute | Description | Type | Default |
|---|---|---|---|
| v-model:show | Whether to show ImagePreview | boolean | false |
| images | Images URL list | string[] | [] |
| startPosition | Start position | number | string | 0 |
| swipeDuration | Animation duration (ms) | number | string | 300 |
| showIndex | Whether to show index | boolean | true |
| showIndicators | Whether to show indicators | boolean | false |
| loop | Whether to enable loop | boolean | true |
| beforeClose | Callback function before close | Function | - |
| closeable | Whether to show close icon | boolean | false |
| closeIcon | Close icon name | string | clear |
| closeIconPosition | Close icon position | 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 | - |
| maxZoom | Max zoom | number | string | 3 |
| minZoom | Min zoom | number | string | 1/3 |
| closeOnClickImage | Whether to close when clicking image | boolean | true |
| closeOnClickOverlay | Whether to close when clicking overlay | boolean | true |
| vertical | Whether to enable vertical gesture | boolean | false |
📡 Events
Stay connected with user interactions through these comprehensive event handlers:
| Event | Description | Arguments |
|---|---|---|
| close | Triggered when closing | - |
| closed | Triggered when closed | - |
| change | Triggered when current image changed | index: number |
| scale | Triggered when scaling | onScale Parameters |
| longPress | Triggered when long press | onScale Parameters |
🛠️ Methods
Control your ImagePreview programmatically with these powerful methods:
| Name | Description | Attribute | Return value |
|---|---|---|---|
| swipeTo | Swipe to target index | index: number, options?: SwipeToOptions | - |
📝 Types
The component exports comprehensive type definitions for enhanced TypeScript development:
importtype { ImagePreviewProps, ImagePreviewOptions, ImagePreviewInstance, ImagePreviewScaleEventParams, } from'vant';ImagePreviewInstance is the type of component instance:
import { ref } from'vue'; importtype { ImagePreviewInstance } from'vant'; const imagePreviewRef = ref<ImagePreviewInstance>(); imagePreviewRef.value?.swipeTo(1);🎰 Slots
Customize every aspect of your image preview with these powerful slot options:
| 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, onLoad: load image, style: current image style } |
🔒 onClose Parameters
Access detailed information when the preview closes:
| Attribute | Description | Type |
|---|---|---|
| url | URL of current image | number |
| index | Index of current image | number |
🔍 onScale Parameters
Monitor scaling interactions with precise data:
| Attribute | Description | Type |
|---|---|---|
| index | Index of current image | number |
| scale | scale of current image | number |
🎨 Theming
🎯 CSS Variables
Transform your image preview's appearance with these comprehensive styling variables. Refer to ConfigProvider component for global theming options.
| 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 | - |