Skip to content

Design system

Documentation

DesignComponents / Image

Components / Image

Stable

Image

Render responsive images with meaningful alternatives, load fallbacks, and an optional preview dialog.

On this page

Examples

Responsive image with preview

Preserve a meaningful alt description and open a larger version in the shared Dialog.

Responsive preview image

Contain inside a fixed frame

Use contain for artwork that should stay fully visible inside a known frame.

Green triangle poster

Contained poster image

Load failure fallback

A failed image shows an accessible fallback in the same reserved region.

Workspace avatar

Image fallback state

Try the image

Inspect a wide image with preview enabled.

Image property playground

Usage

import { Image } from "@phuctech/ui/components/image";

<Image src={src} alt="Quarterly results chart" preview loading="lazy" />

Behavior

Image renders a native responsive img, forwards native image attributes such as dimensions, loading, and decoding, and does not fetch metadata. The shared package does not choose a framework-specific image optimizer. When loading fails, the supplied fallback (or default message) replaces the image. Preview opens the same source in the shared Dialog.

API

Component API
PropTypeDefaultDescriptionConstraints
src / altstring / stringrequiredImage source and text alternative.Use alt empty only when the image is decorative.
previewbooleanfalseOpens the image in a modal preview.Preview uses the shared Dialog and returns focus to its trigger.
fit"cover" | "contain""cover"Object fit utility class.Set a frame size through className or native dimensions.
fallbackReactNode"Image unavailable"Content shown after a load error.Keep the fallback meaningful for the same image purpose.
loading / decoding / width / height / srcSet / sizesnative img attributesbrowser defaultsForwards standard browser image behavior.Use dimensions or an aspect ratio to reduce layout shifts.
onErrorReactEventHandler<HTMLImageElement>—Composes with the internal fallback handling.Do not suppress the fallback by throwing from the handler.

Accessibility

Meaningful images require a text alternative. The preview trigger names the image, the modal title repeats that description, and load failure keeps the same accessible name. The decorative fit and frame styling carry no meaning.

  • Dialog provides the shared modal preview behavior.
  • Avatar adds initials and status for people or entities.