SuspenseImage

SuspenseImage is a component and hook that load images asynchronously with support for React Suspense. Rendering is suspended until the image is fully loaded, providing a smooth loading experience.

Both the SuspenseImage component and the useSuspenseImage hook use an internal cache to prevent the same image from being loaded multiple times. In SSR environments, they ensure that an <img> tag is included in the server-rendered HTML.

SuspenseImage

The SuspenseImage component loads an image asynchronously and suspends rendering until the image is ready. It uses the render prop pattern to provide the loaded image element.

import { SuspenseImage, Suspense } from '@suspensive/react'
 
function ImageExample() {
  return (
    <Suspense fallback={<div>Loading image...</div>}>
      <SuspenseImage src="https://example.com/image.jpg">
        {(img) => <img src={img.src} alt="Example" />}
      </SuspenseImage>
    </Suspense>
  )
}

import { SuspenseImage, Suspense } from '@suspensive/react'

export function ImageExample() {
  return (
    <Suspense fallback={<div style={{ padding: 20 }}>Loading image...</div>}>
      <SuspenseImage src="https://picsum.photos/400/300">
        {(img) => (
          <img
            src={img.src}
            alt="Example"
            style={{ maxWidth: '100%', height: 'auto' }}
          />
        )}
      </SuspenseImage>
    </Suspense>
  )
}

props.src

The source URL of the image to load.

props.children

A render prop that receives the loaded HTMLImageElement and returns a React node.

useSuspenseImage

The useSuspenseImage hook loads an image asynchronously and suspends the component until the image is ready. It returns the loaded HTMLImageElement directly.

import { useSuspenseImage, Suspense } from '@suspensive/react'
 
function ImageComponent() {
  const img = useSuspenseImage('https://example.com/image.jpg')
 
  return <img src={img.src} alt="Example" />
}
 
function App() {
  return (
    <Suspense fallback={<div>Loading image...</div>}>
      <ImageComponent />
    </Suspense>
  )
}

import { useSuspenseImage, Suspense } from '@suspensive/react'

function ImageComponent() {
  const img = useSuspenseImage('https://picsum.photos/400/300')

  return (
    <img
      src={img.src}
      alt="Example"
      style={{ maxWidth: '100%', height: 'auto' }}
    />
  )
}

export function App() {
  return (
    <Suspense fallback={<div style={{ padding: 20 }}>Loading image...</div>}>
      <ImageComponent />
    </Suspense>
  )
}

Parameters

• src (string): The source URL of the image to load.

Return value

• HTMLImageElement: The loaded image element. In SSR environments, a mock object with a src property is returned.

Image Caching

Both SuspenseImage and useSuspenseImage use an internal cache to avoid reloading the same image multiple times. Once an image has been loaded, subsequent requests for the same image will reuse the cached version.

import { useSuspenseImage, Suspense } from '@suspensive/react'
 
function MultipleImages() {
  const img1 = useSuspenseImage('https://example.com/image.jpg')
  const img2 = useSuspenseImage('https://example.com/image.jpg') // uses cache
 
  return (
    <>
      <img src={img1.src} alt="Image 1" />
      <img src={img2.src} alt="Image 2" />
    </>
  )
}

Server-Side Rendering (SSR)

In SSR environments, SuspenseImage and useSuspenseImage return a mock object immediately instead of suspending. This ensures that an <img> tag is included in the server-rendered HTML for SEO purposes.

The mock object has the following shape:

{ src: string, complete: false } as HTMLImageElement

This allows the initial HTML to contain the image tag, while the actual image loading occurs on the client side.