---
title: Resource Loading Optimization
docType: default
---

# Resource Loading Optimization

Images are the most common resource type in miniapps and a significant factor in performance. Poor image usage leads to larger packages, slower page loading, and higher memory usage.

## Use Lazy Loading

For pages with large numbers of images (such as list pages or masonry layouts), lazy loading prevents all images from loading at once, reducing first-screen render pressure and network bandwidth consumption.

The `Image` component provides a `lazyLoad` prop. When enabled, images only start loading when they enter or are about to enter the visible area:

```tsx
import { Image } from '@ray-js/ray';

<Image src={item.imageUrl} lazyLoad />
```

When to use lazy loading:

| Scenario | Use Lazy Loading |
| -------- | ---------------- |
| Images in long lists | Recommended |
| Masonry / image wall | Recommended |
| Key images visible on first screen | Not recommended (delays display) |
| Carousel / Banner | Not recommended (should preload) |

## Avoid Overusing widthFix / heightFix Mode

The `Image` component's `widthFix` and `heightFix` modes dynamically adjust image dimensions after loading, causing layout reflow and jitter.

Fix: specify dimensions in advance, or use an aspect-ratio container to reserve space:

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

{/* ❌ Avoid: widthFix with uncertain height */}
<Image src={imageUrl} mode="widthFix" style={{ width: '100%' }} />

{/* ✅ Recommended: specify dimensions in advance */}
<Image src={imageUrl} mode="aspectFill" style={{ width: '100%', height: '400rpx' }} />

{/* ✅ Recommended: aspect-ratio container (16:9 example) */}
<View style={{ position: 'relative', width: '100%', paddingBottom: '56.25%', overflow: 'hidden' }}>
  <Image
    src={imageUrl}
    style={{ position: 'absolute', top: 0, left: 0, width: '100%', height: '100%' }}
  />
</View>
```

## Image Size Optimization

Use image sizes that match the display size. Avoid loading full-resolution originals.

Use 2x images for a good balance between quality and performance:

| Display size | 1x image | 2x image | 3x image |
| ------------ | -------- | -------- | -------- |
| 100 × 100 | 100 × 100 | 200 × 200 | 300 × 300 |

## Checklist

| Check Item | Optimization |
| ---------- | ------------ |
| All list images loading at once | Use `lazyLoad` prop to enable lazy loading |
| Using widthFix / heightFix mode | Specify dimensions in advance or use aspect-ratio container |
| Loading images larger than needed | Resize images to match display dimensions |