Image

17:06

Description

An enhanced wrapper around uni-app's native image: built-in loading / error placeholders (replaceable via the loading / error slots or loading-icon / error-icon), plus fade transition, shape and border-radius corners, bg-color placeholder background, and lazy-load. Numeric width / height are treated as px; unset means width 100% and height auto.

Compatibility

Platform	Support
App	✅ Supported
H5	✅ Supported
WeChat Mini Program	✅ Supported (`webp`, `show-menu-by-longpress` take effect on WeChat Mini Program only)

Examples

Basic Usage

square (small radius 4px) by default; customize size via width / height. See the example below for shapes.

View source

vue

<template>
    <view class="row">
        <ux-image src="https://placehold.co/100x100.png" width="100" height="100" />
        <ux-image custom-class="gap" src="https://placehold.co/200x200.png" width="200" height="200" />
    </view>
</template>

<style scoped>
.row {
    display: flex;
    flex-direction: row;
    align-items: center;
}
.gap {
    margin-left: 12px;
}
</style>

Radius & Shape

shape controls the shape: square (small radius 4px, default) / circle (perfect circle); border-radius takes precedence as soon as it is set, and 0 gives a true sharp corner.

View source

vue

<template>
    <!-- shape 两档全演示：square 小圆角（4px，不传即此档） / circle 正圆 -->
    <view class="row">
        <ux-image src="https://placehold.co/100x100.png" width="100" height="100" shape="square" />
        <ux-image custom-class="gap" src="https://placehold.co/100x100.png" width="100" height="100" shape="circle" />
    </view>
    <!-- border-radius 一经传入即优先于 shape 预设，传 0 即真直角 -->
    <view class="row">
        <ux-image src="https://placehold.co/100x100.png" width="100" height="100" :border-radius="10" />
        <ux-image custom-class="gap" src="https://placehold.co/100x100.png" width="100" height="100" :border-radius="0" />
    </view>
</template>

<style scoped>
.row {
    display: flex;
    flex-direction: row;
    align-items: center;
}
.gap {
    margin-left: 12px;
}
</style>

Load Error State

Shows an error placeholder icon on failure, customizable via error-icon.

View source

vue

<template>
    <ux-image src="https://invalid.example.com/not-found.png" width="100" height="100" />
</template>

Crop Mode

mode controls crop/scale. Compare aspectFit (full view) vs aspectFill (fills container, crops overflow).

View source

vue

<template>
    <view class="row">
        <ux-image src="https://placehold.co/600x200.png" width="100" height="100" mode="aspectFit" />
        <ux-image custom-class="gap" src="https://placehold.co/600x200.png" width="100" height="100" mode="aspectFill" />
    </view>
</template>

<style scoped>
.row {
    display: flex;
    flex-direction: row;
    align-items: center;
}
.gap {
    margin-left: 12px;
}
</style>

Fade-in Animation

fade controls the fade-in transition on load. Compare no animation vs 500ms fade-in.

View source

vue

<template>
    <view class="row">
        <ux-image src="https://placehold.co/100x100.png" width="100" height="100" :fade="false" :lazy-load="false" />
        <ux-image custom-class="gap" src="https://placehold.co/100x100.png" width="100" height="100" :fade="true" :duration="500" />
    </view>
</template>

<style scoped>
.row {
    display: flex;
    flex-direction: row;
    align-items: center;
}
.gap {
    margin-left: 12px;
}
</style>

Background Placeholder

bg-color sets the loading/error placeholder background. Defaults to the theme background; a failing image keeps the placeholder visible for easy comparison.

View source

vue

<template>
    <view class="row">
        <ux-image src="https://invalid.example.com/bg-not-found.png" width="100" height="100" />
        <ux-image custom-class="gap" src="https://invalid.example.com/bg-not-found.png" width="100" height="100" :bg-color="'#f5222d'" />
    </view>
</template>

<style scoped>
.row {
    display: flex;
    flex-direction: row;
    align-items: center;
}
.gap {
    margin-left: 12px;
}
</style>

Custom Slots

The error slot fully customizes the failure placeholder, or use loading-icon/error-icon for built-in icons. Left: custom; right: loading icon.

View source

vue

<template>
    <view class="row">
        <ux-image src="https://invalid.example.com/slot-not-found.png" width="100" height="100" :show-error="true">
            <template #error>
                <view class="holder">
                    <ux-icon name="info-circle" color="#f5222d" size="20" />
                    <text class="tip">自定义失败</text>
                </view>
            </template>
        </ux-image>
        <ux-image custom-class="gap" src="https://placehold.co/100x100.png?delay=3000" width="100" height="100" loading-icon="star" :show-loading="true" :show-error="false" />
    </view>
</template>

<style scoped>
.row {
    display: flex;
    flex-direction: row;
    align-items: center;
}
.gap {
    margin-left: 12px;
}
.holder {
    display: flex;
    flex-direction: column;
    align-items: center;
}
.tip {
    font-size: 10px;
    color: #f5222d;
    margin-top: 4px;
}
</style>

API

Props

Property	Description	Type	Default	Version
`customStyle`	Custom root element style	`string \| UTSJSONObject`	`-`	-
`customClass`	Custom root element style class	`string`	`''`	-
`src`	Image URL	`string`	`''`	-
`mode`	Crop mode	`ImgMode`	`'aspectFit'`	-
`width`	Width	`string \| number`	`'100%'`	-
`height`	Height	`string \| number`	`'auto'`	-
`shape`	Image shape (see ImageShape in types/global.uts): square – small radius 4px (default), circle – perfect circle	`ImageShape`	`'square'`	-
`borderRadius`	Corner radius; `''` is a sentinel meaning unset (pass 0 for an explicit sharp corner, which takes precedence over `shape`)	`string \| number`	`''`	-
`lazyLoad`	Whether to lazy-load	`boolean`	`true`	-
`showMenuByLongpress`	Whether long-press shows the Mini Program code recognition menu	`boolean`	`true`	-
`loadingIcon`	Loading icon	`string`	`'photo'`	-
`errorIcon`	Error icon	`string`	`'error-circle'`	-
`showLoading`	Whether to show the loading icon	`boolean`	`true`	-
`showError`	Whether to show the error icon	`boolean`	`true`	-
`fade`	Whether to enable the fade-in effect	`boolean`	`true`	-
`webp`	Only for network resources; WeChat Mini Program only	`boolean`	`false`	-
`duration`	Transition duration	`string \| number`	`500`	-
`bgColor`	Background color	`string`	`''`	-

Events

Event	Description	Params	Version
`click`	Fired when the image is clicked	-	-
`error`	Fired when the image fails to load	`err: UniImageErrorEvent`	-
`load`	Fired when the image loads successfully	-	-

Slots

Slot	Description	Version
`loading`	Custom loading placeholder (shows `loading-icon` by default)	-
`error`	Custom error placeholder (shows `error-icon` by default)	-

Notes

border-radius=0 means an explicit sharp corner and overrides the shape preset; when unset, the radius follows shape (square 4px / circle).
showMenuByLongpress defaults to true but only takes effect on WeChat Mini Program.
webp is supported on WeChat Mini Program only, and only for network images.
duration only applies when fade is true; the unit is ms.
On load failure the component switches to the error placeholder; disable showError or take over with the error slot to customize.

Image ​

Description ​

Compatibility ​

Examples ​

Basic Usage ​

Radius & Shape ​

Load Error State ​

Crop Mode ​

Fade-in Animation ​

Background Placeholder ​

Custom Slots ​

API ​

Props ​

Events ​

Slots ​

Notes ​

Image

Description

Compatibility

Examples

Basic Usage

Radius & Shape

Load Error State

Crop Mode

Fade-in Animation

Background Placeholder

Custom Slots

API

Props

Events

Slots

Notes