Image
Data Display

Image

Displays an image with reserved dimensions, a loading placeholder, and an error fallback.

Component behavior

Image reserves layout space, displays a loading state, and renders fallback content after a load failure. Off-screen loading uses the browser's native lazy-loading behavior.

Use cases
  • Remote images other than user avatars.
  • Image grids or feeds that require reserved layout space.
  • Images that need a fallback for missing or failed URLs.
Alternatives

Avatar: the image represents a person and should fall back to initials.

Icon: the content is an icon.

Props

Image extends ImgHTMLAttributes<HTMLImageElement> (minus placeholder and onError, which it handles). Unlisted props (srcSet, sizes, referrerPolicy) pass through to the <img>.

ImageProps props
PropTypeDefaultDescription
srcstring—Image URL. Missing or empty renders the fallback.
altstring—Required, as on <img>. Pass "" for decorative images.
rationumber | string—Reserves the box before the bytes arrive: 16 / 9, "4 / 3", or a number.
fitImageFit"cover""cover" | "contain" | "fill" | "none" | "scale-down".
roundedkeyof RadiusScale—Corner radius token.
skeletonbooleantrueLoading placeholder displayed while the image loads.
fallbackReactNode—Rendered when the image fails, or when src is missing.
fadebooleantrueEnables a fade transition when loading completes.
loading"lazy" | "eager""lazy"Native lazy loading. Use "eager" above the fold.
onStatusChange(status: ImageStatus) => void—"loading" | "loaded" | "error", as it changes.

Examples

Reserved box

Image with ratio

Failure

A failed image request displays fallback. The default fallback is a neutral frame with a strike-through.

Image fallback

Fit

Image fit
ImportTSX
import { Image, LazyImage } from "@solarius/onset";
import type { ImageFit, ImageStatus } from "@solarius/onset";

<Image
  src={asset.url}
  alt={asset.name}
  ratio={16 / 9}
  rounded="md"
  fallback={<Text size="xs" color="fg-faint">Preview unavailable</Text>}
/>

// Above the fold, where lazy loading only delays the thing being looked at:
<Image src={hero} alt="" ratio={21 / 9} loading="eager" />

See Avatar for people, which falls back to initials on a dead URL, and Skeleton for the placeholder this renders while loading.