# ImagePreloader

*Category:* Components
*Section:* Misc
*Source:* https://uikit.developers.rio.cloud/#/components/imagePreloader
*Captured:* 2026-04-27T14:58:19.859Z

Use the preloader for controlling the various states when fetching the image. It allows to handle the failure case as well.

## ImagePreloader

### Example: Example 1

With Image tag

As background image without spinner

Fallback case

#### React (tsx)

```tsx
import ImagePreloader from '@rio-cloud/rio-uikit/ImagePreloader';
import AspectRatioPlaceholder from '@rio-cloud/rio-uikit/AspectRatioPlaceholder';
import Spinner from '@rio-cloud/rio-uikit/Spinner';

export default () => (
    <div className='row'>
        <div className='col-md-4'>
            <div className='h5 ellipsis-1'>With Image tag</div>
            {imageExample}
        </div>
        <div className='col-md-4'>
            <div className='h5 ellipsis-1'>As background image without spinner</div>
            {backgroundImageExample}
        </div>
        <div className='col-md-4'>
            <div className='h5 ellipsis-1'>Fallback case</div>
            {failedImageExample}
        </div>
    </div>
);

const fallback = (
    <AspectRatioPlaceholder width={1000} height={562}>
        <div className='text-size-h3 display-grid place-items-center position-absolute inset-0'>
            <span className='rioglyph rioglyph-missing text-size-200pct text-color-gray' />
        </div>
    </AspectRatioPlaceholder>
);

const imageExample = (
    <ImagePreloader src='https://picsum.photos/1000/560'>
        {({ status, image }) => {
            switch (status) {
                case 'FAILED':
                    return fallback;

                case 'LOADED':
                    // When image has been loaded, render the image tag
                    return <img src={image.src} className='img-responsive ani-fade-in' alt='Awesome stuff.' />;

                default:
                    return (
                        <AspectRatioPlaceholder width={1000} height={560}>
                            <div className='display-grid place-items-center position-absolute inset-0'>
                                <Spinner isInverse={false} />
                            </div>
                        </AspectRatioPlaceholder>
                    );
            }
        }}
    </ImagePreloader>
);

const backgroundImageExample = (
    <ImagePreloader src='https://picsum.photos/1000/560'>
        {({ status, image }) => {
            switch (status) {
                case 'FAILED':
                    return fallback;

                case 'LOADED':
                    // When image has been loaded, set it as background
                    return (
                        <div
                            className='bg-size-cover bg-position-center ani-fade-in'
                            style={{ backgroundImage: `url(${image.src})` }}
                        >
                            <AspectRatioPlaceholder width={1000} height={560} />
                        </div>
                    );

                default:
                    return null;
            }
        }}
    </ImagePreloader>
);

const failedImageExample = (
    <ImagePreloader src='https://not-there'>
        {({ status }) => {
            if (status === 'FAILED') {
                return fallback;
            }
            return null;
        }}
    </ImagePreloader>
);
```

#### HTML (html)

```html
<div class="row">
    <div class="col-md-4">
        <div class="h5 ellipsis-1">With Image tag</div>
        <div class="position-relative " style="aspect-ratio: 1000 / 560;">
            <div class="display-grid place-items-center position-absolute inset-0">
                <div class="spinnerInfoBox display-flex justify-content-center align-items-center height-100pct">
                    <div class="spinner">
                        <div>
                        </div>
                        <div>
                        </div>
                        <div>
                        </div>
                        <div>
                        </div>
                    </div>
                </div>
            </div>
        </div>
    </div>
    <div class="col-md-4">
        <div class="h5 ellipsis-1">As background image without spinner</div>
    </div>
    <div class="col-md-4">
        <div class="h5 ellipsis-1">Fallback case</div>
        <div class="position-relative " style="aspect-ratio: 1000 / 562;">
            <div class="text-size-h3 display-grid place-items-center position-absolute inset-0">
                <span class="rioglyph rioglyph-missing text-size-200pct text-color-gray">
                </span>
            </div>
        </div>
    </div>
</div>
```

#### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| src | string | — | The URL of the image to load. |
| onLoaded | (image: HTMLImageElement) => void | — | Invoked when the image is loaded. |
| onFailed | (image: HTMLImageElement) => void | — | Invoked when the image failed to load. |
| isAnonymous | boolean | false | Whether to set the "crossOrigin" to "anonymous". |
| children | (props: { status: ImagePreloaderStatus; image: HTMLImageElement; }) => JSX.Element \| null | — | A render function can be used to access both the current state and the image element. Using this, you can decide how to render the different states and/or the loaded image. The function will receive props containing the status and image properties. status will be one of PENDING, FAILED or LOADED. image is the Image element. |