---
name: "image"
mode: "component"
versionRequirements:
  - { name: "Base Library", version: "2.10.0" }
title: "image - Image"
---

## image

> [VERSION] Base Library >= 2.10.0

### Description

Image component supporting multiple cropping and scaling modes.

### Props

| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `src` | `string` | Yes | - | Image URL |
| `mode` | `string` | No | `"scaleToFill"` | Image cropping and scaling mode |
| `lazy-load` | `boolean` | No | `false` | Enable lazy loading; load the image after it enters the viewport |
| `fade-duration` | `number` | No | `0` | Fade-in animation duration, in milliseconds |

#### Events

| Event | Type | Description |
| --- | --- | --- |
| `load` | `(event: ImageLoadEvent) => void` | Fires when the image has loaded |
| `error` | `(event: ImageErrorEvent) => void` | Fires when image loading fails |

**ImageLoadEvent**

| Field | Type | Description |
| --- | --- | --- |
| `type` | `"load"` | Event type |
| `detail` | `ImageLoadDetail` | Event data |

**ImageErrorEvent**

| Field | Type | Description |
| --- | --- | --- |
| `type` | `"error"` | Event type |
| `detail` | `ImageErrorDetail` | Event data |

### Examples

#### Basic usage and scaling modes

*index.tyml*

```xml
// index.tyml
<view class="wrap">
  <text class="title">scaleToFill (default)</text>
  <image src="https://example.com/pic.jpg" mode="scaleToFill" class="img" />

  <text class="title">aspectFit</text>
  <image src="https://example.com/pic.jpg" mode="aspectFit" class="img" />

  <text class="title">aspectFill</text>
  <image src="https://example.com/pic.jpg" mode="aspectFill" class="img" />

  <text class="title">widthFix</text>
  <image src="https://example.com/pic.jpg" mode="widthFix" class="img-auto" />
</view>
```

*index.tyss*

```css
.wrap { padding: 20rpx; }
.title { font-size: 28rpx; color: #666; margin: 20rpx 0 10rpx; }
.img { width: 300rpx; height: 300rpx; background-color: #f0f0f0; }
.img-auto { width: 300rpx; }
```

*index.js*

```javascript
Page({});
```

#### Lazy loading and event handling

*index.tyml*

```xml
<view class="wrap">
  <image
    src="{{imgSrc}}"
    mode="widthFix"
    lazy-load="{{true}}"
    fade-duration="{{300}}"
    class="img"
    bindload="onLoad"
    binderror="onError"
  />
  <text ty:if="{{info}}">{{info}}</text>
</view>
```

*index.tyss*

```css
.wrap { padding: 20rpx; }
.img { width: 100%; }
```

*index.js*

```javascript
Page({
  data: {
    imgSrc: 'https://example.com/pic.jpg',
    info: '',
  },
  onLoad(e) {
    this.setData({
      info: 'Loaded successfully: ' + e.detail.width + 'x' + e.detail.height,
    });
  },
  onError(e) {
    this.setData({ info: 'Load failed: ' + e.detail.errMsg });
  },
});
```


### Notes

- Some low-end devices have poor WebP compatibility, which may cause images to fail to display or render incorrectly. Prefer image formats with more stable compatibility; if WebP must be used, verify rendering on target devices and provide a fallback image.

### FAQ

#### Does image support lazy loading?

Yes, lazy loading can be enabled by configuring the `lazy-load` attribute.

#### Images appear compressed when using the image component on a real device?

It is recommended to set the `mode` value to `widthFix`.

#### Image URL formats

- Network image: `src="https://tuya.com/img.png"`
  - Network images must support HTTPS protocol.
- Base64 image: `src="data:image/png;base64,xxx"`
- Absolute path: `src="/assets/img.png"`
  - The `/` in an absolute path represents the root directory. If the `miniprogramRoot` field is configured in `project.tuya.json`, then `/` represents the `miniprogramRoot` path.
- Relative path: `src="./assets/img.png"` **(not recommended)**
  - Relative paths are only supported within pages, not inside custom components.
  - Relative paths are relative to the current file's location. They are not recommended because they are affected by file position and are harder to maintain.