---
name: "Image"
mode: "component"
versionRequirements:
  - { name: "@ray-js/ray", version: "0.5.10" }
title: "Image - Image"
---

## Image

> [VERSION] @ray-js/ray >= 0.5.10

### Description

Image component supporting multiple cropping and scaling modes.

### Props

| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `src` | `string` | No | - | Image source URL |
| `mode` | `"scaleToFill" \| "aspectFit" \| "aspectFill" \| "widthFix" \| "heightFix" \| "top" \| "bottom" \| "center" \| "left" \| "right" \| "top left" \| "top right" \| "bottom left" \| "bottom right"` | No | `"scaleToFill"` | Image cropping and scaling modes |
| `lazyLoad` | `boolean` | No | `false` | Lazy load; loads after entering a certain viewport range |
| `fadeDuration` | `number` | No | `0` | Fade-in duration during loading, in ms |
| `onError` | `(event: ImageErrorEvent) => void` | No | - | Triggered when loading fails |
| `onLoad` | `(event: ImageLoadEvent) => void` | No | - | Triggered when loading completes |

### Referenced Types

##### `interface` ImageErrorEvent

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

##### `interface` ImageLoadEvent

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

##### `interface` ImageErrorDetail

| Property | Type | Description |
| --- | --- | --- |
| `errMsg` | `string` | Error message |

##### `interface` BaseEvent

| Property | Type | Description |
| --- | --- | --- |
| `type` | `string` | Event type |
| `timeStamp` | `number` | Time in milliseconds since the page opened |
| `target` | `Target` | Source component of the event |
| `currentTarget` | `Target` | Collection of property values for the current component |
| `mark` | `any` | Event mark data |

##### `interface` ImageLoadDetail

| Property | Type | Description |
| --- | --- | --- |
| `width` | `number` | Image width, in px |
| `height` | `number` | Image height, in px |

##### `interface` Target

| Property | Type | Description |
| --- | --- | --- |
| `id` | `string` | id of the event source component |
| `dataset` | `Record<string, unknown>` | Collection of custom attributes from the `dataset` on the event source component |


### Valid Values

##### `mode` valid values

| Value | Description |
| --- | --- |
| `"scaleToFill"` | Scaling mode: scales the image without preserving the aspect ratio, stretching its width and height to completely fill the image element |
| `"aspectFit"` | Scale mode: preserve aspect ratio and ensure the long edge is fully visible |
| `"aspectFill"` | Scale mode: preserve aspect ratio and ensure only the short edge is fully visible |
| `"widthFix"` | Scale mode: fixed width, auto height; preserve the original aspect ratio |
| `"heightFix"` | Scale mode: fixed height, auto width; preserve the original aspect ratio |
| `"top"` | Crop mode: do not scale; display only the top region of the image |
| `"bottom"` | Crop mode: do not scale; display only the bottom region of the image |
| `"center"` | Crop mode: do not scale; display only the center region of the image |
| `"left"` | Crop mode: do not scale; display only the left region of the image |
| `"right"` | Crop mode: do not scale; display only the right region of the image |
| `"top left"` | Crop mode: do not scale; display only the top-left region of the image |
| `"top right"` | Crop mode: do not scale; display only the top-right region of the image |
| `"bottom left"` | Crop mode: do not scale; display only the bottom-left region of the image |
| `"bottom right"` | Crop mode: do not scale; display only the bottom-right region of the image |


### Examples

#### Basic usage

```tsx
import React from 'react';
import { Image, View } from '@ray-js/ray';

export default function () {
  return (
    <View style={{ padding: '20px' }}>
      <Image
        src="https://images.tuyacn.com/rms-static/602542e0-48f8-11f1-8d53-258e63d3fe0e-1778036702734.jpeg"
        style={{ width: '200px', height: '200px' }}
        onLoad={(e) => console.log('Image loaded:', e.detail)}
        onError={(e) => console.log('Image load failed:', e.detail)}
      />
    </View>
  );
}
```

#### Scaling modes

```tsx
import React, { useState } from 'react';
import { Image, View, Text, Button } from '@ray-js/ray';

export default function () {
  const [mode, setMode] = useState<string>('scaleToFill');
  const imgSrc = 'https://images.tuyacn.com/rms-static/602542e0-48f8-11f1-8d53-258e63d3fe0e-1778036702734.jpeg';

  return (
    <View style={{ padding: '20px' }}>
      <Text style={{ marginBottom: '10px' }}>Current mode: {mode}</Text>
      <Image
        src={imgSrc}
        mode={mode}
        style={{ width: '300px', height: '200px', border: '1px solid #eee' }}
      />
      <View style={{ marginTop: '20px', display: 'flex', flexDirection: 'row', gap: '8px', flexWrap: 'wrap' }}>
        <Button size="mini" onClick={() => setMode('scaleToFill')}>
          scaleToFill
        </Button>
        <Button size="mini" onClick={() => setMode('aspectFit')}>
          aspectFit
        </Button>
        <Button size="mini" onClick={() => setMode('aspectFill')}>
          aspectFill
        </Button>
        <Button size="mini" onClick={() => setMode('widthFix')}>
          widthFix
        </Button>
      </View>
    </View>
  );
}
```

#### Lazy load and fade-in

```tsx
import React from 'react';
import { Image, View, Text } from '@ray-js/ray';

export default function () {
  const imgSrc = 'https://images.tuyacn.com/rms-static/602542e0-48f8-11f1-8d53-258e63d3fe0e-1778036702734.jpeg';

  return (
    <View style={{ padding: '20px' }}>
      <Text style={{ marginBottom: '10px' }}>Lazy load + fade-in 500ms:</Text>
      <Image
        src={imgSrc}
        lazyLoad
        fadeDuration={500}
        style={{ width: '300px', height: '200px' }}
        onLoad={(e) => console.log('Loaded:', e.detail)}
        onError={(e) => console.log('Load failed:', e.detail)}
      />
    </View>
  );
}
```


### 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.