vant/packages/vant/src/image/README.md

Image

Intro

Enhanced img tag with multiple image fill modes, support for image lazy loading, loading hint, loading failure hint.

Install

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

import { createApp } from 'vue';
import { Image as VanImage } from 'vant';

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

Usage

Basic Usage

<van-image
  width="100"
  height="100"
  src="https://fastly.jsdelivr.net/npm/@vant/assets/cat.jpeg"
/>

Fit Mode

Same as object-fit.

<van-image
  width="10rem"
  height="10rem"
  fit="contain"
  src="https://fastly.jsdelivr.net/npm/@vant/assets/cat.jpeg"
/>

Position

Same as object-position.

<van-image
  width="10rem"
  height="10rem"
  fit="cover"
  position="left"
  src="https://fastly.jsdelivr.net/npm/@vant/assets/cat.jpeg"
/>

Round

Show round image, it may not works at fit=contain and fit=scale-down.

<van-image
  round
  width="10rem"
  height="10rem"
  src="https://fastly.jsdelivr.net/npm/@vant/assets/cat.jpeg"
/>

Lazy Load

<van-image
  width="100"
  height="100"
  lazy-load
  src="https://fastly.jsdelivr.net/npm/@vant/assets/cat.jpeg"
/>

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

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

API

Props

Attribute	Description	Type	Default
src	Src	string	-
fit	Fit mode, same as object-fit	string	fill
position v3.4.2	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	0
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 v3.0.11	Icon size	number | string	32px
icon-prefix	Icon className prefix	string	van-icon

fit optional value

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

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

Name	Description
default	Custom the content below the image
loading	Custom loading placeholder
error	Custom error placeholder

Types

The component exports the following type definitions:

import type { ImageFit, ImagePosition, ImageProps } from 'vant';

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