Image

The Image component provides a consistent way to display images with responsive sizing, loading placeholders, and fallback content. It renders a native HTML <img> by default and can also use an image component configured for your framework.

ImportCopy Anchor Link

import { Image } from "@puzzle-ui/ui";

Basic usageCopy Anchor Link

Provide a source and alternative text. Set the intrinsic dimensions to reserve space while the image loads.

The width and height props describe the image's intrinsic dimensions in pixels. They can be inferred when src is a static image import with src, width, and height fields.

Fitting and positioningCopy Anchor Link

Use fit to control how the image fills its box, and position to align the image content within that box. These correspond to CSS object-fit and object-position; the defaults are "cover" and "center".

The radius prop sets the border radius on the image container. It accepts the presets "none", "sm", "md", "lg", "xl", and "full", as well as a CSS border-radius value.

Aspect ratio and fillCopy Anchor Link

Set aspectRatio to make the image fill a full-width container with a chosen ratio.

<Image
  src="/images/landscape.webp"
  alt="Mountain landscape"
  aspectRatio="16 / 9"
/>

Use fill to position the image across its parent container. The parent must have a defined size; set aspectRatio on the Image or give the parent an explicit height.

<div style={{ width: "100%", height: 240 }}>
  <Image
    src="/images/landscape.webp"
    alt="Mountain landscape"
    fill
    fit="cover"
  />
</div>

Loading placeholdersCopy Anchor Link

Use loadingPlaceholder to display custom content over the image while it loads.

<Image
  src="/images/landscape.webp"
  alt="Mountain landscape"
  loadingPlaceholder={<span>Loading image...</span>}
/>

Alternatively, set placeholder="blur" and provide a small preview through blurDataURL. A static image import can provide this value automatically.

<Image
  src="/images/landscape.webp"
  alt="Mountain landscape"
  placeholder="blur"
  blurDataURL="data:image/jpeg;base64,..."
/>

For native <img> elements, the component displays the blur preview behind the image while it loads. When a framework image component is configured, the placeholder and blurDataURL props are forwarded to it. A custom loadingPlaceholder, when provided, takes precedence over the native blur preview.

FallbacksCopy Anchor Link

Use fallbackSrc to try another image if the primary source fails. Use fallback to render custom content when no usable source is available or all image sources fail.

If neither a usable src nor a fallback is provided, the component renders nothing.

Responsive sourcesCopy Anchor Link

Pass sources to render <source> elements inside a native <picture>. This supports art direction and selecting different formats or files for different media conditions.

<Image
  src="/images/landscape.webp"
  alt="Mountain landscape"
  sources={[
    {
      srcSet: "/images/landscape-mobile.webp",
      media: "(max-width: 640px)",
    },
    {
      srcSet: "/images/landscape.avif",
      type: "image/avif",
    },
  ]}
/>

The standard image props srcSet and sizes are also supported.

Framework image componentsCopy Anchor Link

By default, Image renders a native <img>. You can provide a framework-specific image component with component, or configure one through Theme's components.image. The component prop takes precedence over the theme configuration.

<Image
  component={FrameworkImage}
  src="/images/landscape.webp"
  alt="Mountain landscape"
  quality={85}
  preload
/>

Framework-specific options such as quality, unoptimized, and componentProps are forwarded to a custom image component. preload uses React DOM image preloading for a native <img> and is forwarded to a configured image component.

APICopy Anchor Link

PropsCopy Anchor Link

Native image propsCopy Anchor Link

Image supports the standard React <img> props, including loading, fetchPriority, decoding, crossOrigin, referrerPolicy, onLoad, and onError, as well as aria-* and data-* attributes. Framework-specific props should be passed through componentProps.

TypeScript typesCopy Anchor Link

The component exports ImageProps, ImageSource, ImageSourceData, ImageSourceSet, ImageFit, ImageRadius, and ImagePlaceholder.

ImageSource accepts either a URL string or static image data:

type ImageSource = string | ImageSourceData;

type ImageSourceData = {
  src: string;
  width: number;
  height: number;
  blurDataURL?: string;
  blurWidth?: number;
  blurHeight?: number;
};

AccessibilityCopy Anchor Link

• Provide descriptive alt text for images that convey information.
• Use alt="" when an image is decorative so assistive technology can ignore it.
• If fallback communicates image content, the component exposes it as an image with the provided alt text.
• Native image attributes and event handlers are forwarded to the rendered image element.