Image

Requires:

@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
		No	-	Triggered when loading fails
		No	-	Triggered when loading completes

Valid Values

`mode`

Value	Description	Since
`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

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

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

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.

Image

Description

Props

Valid Values

mode

Examples

Basic usage

Scaling modes

Lazy load and fade-in

#Notes

`mode`

Notes