Image - Vant 4
Image
🖼️ Transform your images into stunning visual experiences! The Image component is your gateway to professional-grade image handling in mobile applications.
🌟 Intro
Meet the supercharged img tag that goes beyond basic image display! With intelligent fill modes, seamless lazy loading, elegant loading states, and graceful error handling, this component ensures your images always look perfect and load efficiently. Whether you're building a photo gallery, product showcase, or content-rich interface, the Image component delivers exceptional performance and user experience.
📦 Install
Get started with professional image handling in seconds! Register the component globally via app.use for instant access throughout your application. Check out Component Registration for additional setup options.
import { createApp } from'vue'; import { ImageasVanImage } from'vant'; const app = createApp(); app.use(VanImage);🎨 Usage
🌟 Basic Usage
Creating beautiful images is as simple as adding a src attribute! The Image component automatically handles loading states and provides a smooth user experience out of the box.
🎯 Fit Mode
Master the art of image presentation! Control exactly how your images fill their containers with powerful fit modes, leveraging the same flexibility as CSS object-fit. From perfect covers to contained displays, achieve the exact visual impact you're aiming for.
📍 Position
Precision positioning at your fingertips! Fine-tune where your images are positioned within their containers using the same control as CSS object-position. Perfect for highlighting specific areas or creating artistic compositions.
⭕ Round
Create stunning circular images with a single property! Perfect for avatars, profile pictures, and modern UI designs. Note: Works best with fill and cover fit modes for optimal visual results.
🚀 Lazy Load
Boost your app's performance with intelligent lazy loading! Images load only when they're about to enter the viewport, dramatically improving initial page load times and reducing bandwidth usage. Essential for image-heavy applications and mobile optimization.
import { createApp } from'vue'; import { Lazyload } from'vant'; const app = createApp(); app.use(Lazyload);🔧 API
🎛️ Props
Customize every aspect of your image display with these comprehensive configuration options:
| Attribute | Description | Type | Default |
|---|---|---|---|
| src | Src | string | - |
| fit | Fit mode, same as object-fit | string | fill |
| position | Position, same as object-position, can be set to top``right``bottom``left or string | string | center |
| alt | Alt | string | - |
| width | Width | *number | string* |
| height | Height | *number | string* |
| radius | Border Radius | *number | string* |
| round | Whether to be round | boolean | false |
block 3.6.3 | Whether the root node is a block element | boolean | false |
| lazy-load | Whether to enable lazy load, should register Lazyload component | boolean | false |
| show-error | Whether to show error placeholder | boolean | true | | show-loading | Whether to show loading placeholder | boolean | true | | error-icon | Error icon | string | photo-fail | | loading-icon | Loading icon | string | photo | | icon-size | Icon size | number | string | 32px | | icon-prefix | Icon className prefix | string | van-icon | | crossorigin | same as crossorigin | string | - | | referrerpolicy | same as referrerpolicy | string | - | | decoding v4.9.20 | same as decoding | string | - |
🎨 Fit Optional Values
Choose the perfect display strategy for your images:
| name | description |
|---|---|
| contain | Keep aspect ratio, fully display the long side of the image |
| cover | Keep aspect ratio, fully display the short side of the image, cutting the long side |
| fill | Stretch and resize image to fill the content box |
| none | Not resize image |
| scale-down | Take the smaller of none or contain |
📡 Events
Stay connected with image lifecycle events:
| Event | Description | Arguments |
|---|---|---|
| click | Emitted when image is clicked | event: MouseEvent |
| load | Emitted when image loaded | event: Event |
| error | Emitted when image load failed | - |
🎰 Slots
Customize loading and error states with powerful slot options:
| Name | Description |
|---|---|
| default | Custom the content below the image |
| loading | Custom loading placeholder |
| error | Custom error placeholder |
📝 Types
The component exports comprehensive type definitions for enhanced TypeScript development:
importtype { ImageFit, ImagePosition, ImageProps } from'vant';🎨 Theming
🎯 CSS Variables
Transform your image component's appearance with these comprehensive styling variables. Refer to ConfigProvider component for global theming options.
| Name | Default Value | Description |
|---|---|---|
| --van-image-placeholder-text-color | var(--van-text-color-2) | - |
| --van-image-placeholder-font-size | var(--van-font-size-md) | - |
| --van-image-placeholder-background | var(--van-background) | - |
| --van-image-loading-icon-size | 32px | - |
| --van-image-loading-icon-color | var(--van-gray-4) | - |
| --van-image-error-icon-size | 32px | - |
| --van-image-error-icon-color | var(--van-gray-4) | - |