#Image

The Image component is a wrapper around the standard HTML <img> tag. It supports all native image properties while introducing resource-preloading capabilities when used with React 19 or newer.

#Usage

You can use the Image component just like a regular <img> tag to render PNG or other format images:

import { Image } from '@rspress/core/theme';

<Image src="/rspress-light-logo.png" alt="Rspress Logo" width="100" />

#Preloading critical images

For above-the-fold imagery (such as PNG hero images) that affects the Largest Contentful Paint (LCP) metric, you can set the preload prop to true.

When preload is active and a src is specified, the component uses ReactDOM.preload under the hood to eagerly load the asset.

index.mdx

import { Image } from '@rspress/core/theme';

<Image
  src="https://lexmin0412.github.io/rspress-template/rspress-light-logo.png"
  alt="Preloaded Hero Logo"
  width="150"
  preload
  fetchPriority="high"
/>

#Responsive images with SrcSet

The preload mechanism honors standard responsive properties. When preloading PNGs, you can define srcSet and sizes to ensure the correct resolution or layout density variant (e.g., @2x.png) is selected by the browser during the preload phase.

index.mdx

import { Image } from '@rspress/core/theme';

<Image
  src="https://lexmin0412.github.io/rspress-template/rspress-light-logo.png"
  srcSet="/rspress-light-logo.png 1x, /[email protected] 2x"
  sizes="(max-width: 600px) 100px, 200px"
  alt="Responsive Rspress Logo"
  width="150"
  preload
/>

#Ref forwarding

The component utilizes React.forwardRef to pass its ref handle down to the underlying <img> element. This can be used to read dimensions or access natural image boundaries once the PNG resource has finished loading.

import { useRef, useEffect } from 'react';
import { Image } from '@rspress/core/theme';

export default function App() {

const imageRef = useRef<HTMLImageElement>(null);
useEffect(() => {
if (imageRef.current) {
console.log('Image natural width:', imageRef.current.naturalWidth);
}
}, []);

return (

<Image 
      ref={imageRef} 
      src="https://lexmin0412.github.io/rspress-template/rspress-light-logo.png" 
      alt="Reference Image" 
      width="100" 
    />
);
}

#Props

The Image component accepts all attributes belonging to standard HTML <img> elements (ImgHTMLAttributes<HTMLImageElement>), alongside the following configuration:

import { ImgHTMLAttributes } from 'react';

export interface ImageProps extends ImgHTMLAttributes<HTMLImageElement> {
  /**
   * Determines whether the image resource should be eagerly preloaded.
   *
   * When set to `true`, and the `src` attribute is provided, the component calls
   * `ReactDOM.preload` (available in React 19 and newer) to pre-load the image.
   * This is recommended for critical, above-the-fold assets (such as hero images)
   * to help improve Largest Contentful Paint (LCP) performance.
   *
   * @default false
   */
  preload?: boolean;
}