Component reference
Image
A product image inside a composed product card.
Preview
Live previewOptional six-digit hex. Clear to restore the preset. Check contrast with your brand color.
Changes apply to this preview only.

Pimolu Studio
In stockA design-system starter with tokens, themes and cross-platform components.
Jean Dupont
Design engineer
Latest case study · 6 min readWidth adapts to the available space
"use client";
import {
Card,
Image,
CardHeader,
CardTitle,
Badge,
CardDescription,
CardContent
} from "@pimolu/react";
export function DemoExample() {
return (
<div
className="grid grid-cols-[repeat(auto-fit,minmax(min(100%,280px),1fr))] gap-6 min-w-0 items-start"
>
<Card>
<Image
src="/images/pimolu-studio.webp"
alt="Pimolu Studio product illustration"
aspectRatio={16 / 9}
fit="cover"
rounded="none"
width={400}
height={300}
/>
<CardHeader>
<div
className="flex flex-wrap items-center gap-3 min-w-0 justify-between"
>
<CardTitle>Pimolu Studio</CardTitle>
<Badge variant="success">In stock</Badge>
</div>
<CardDescription>
A design-system starter with tokens, themes and cross-platform
components.
</CardDescription>
</CardHeader>
<CardContent>
<div
className="flex flex-wrap items-center gap-3 min-w-0 justify-between"
>
<span className="text-2xl font-medium">€49</span>
<span className="text-sm text-muted leading-relaxed">Ships in 2–3 days</span>
</div>
</CardContent>
</Card>
<Card>
<CardHeader>
<div className="flex flex-wrap items-center gap-3 min-w-0">
<Image
src="/images/pimolu-avatar.svg"
alt="Pimolu p emblem on an indigo avatar"
width={128}
height={128}
rounded="full"
containerStyle={{
width: 56
}}
/>
<div>
<CardTitle>Jean Dupont</CardTitle>
<CardDescription>Design engineer</CardDescription>
</div>
</div>
</CardHeader>
<CardContent>
<div className="grid gap-5 min-w-0">
<Image
src="/images/pimolu-studio.webp"
alt="Recent work by Jean Dupont"
aspectRatio={4 / 3}
fit="cover"
rounded="md"
width={400}
height={300}
/>
<span className="text-sm text-muted leading-relaxed">Latest case study · 6 min read</span>
</div>
</CardContent>
</Card>
</div>
);
}More examples
Different configurations and compositions using the real Pimolu API. Each preview runs independently and follows the site appearance.
Cached images
Reuse the image shown below: hide and show another instance to check that cached files reveal their content, not a lasting skeleton.
Aspect ratios
The wrapper reserves the box; the image fills it without shifting the page when it decodes.
Object fit
A square box makes cover, contain, fill and scale-down visibly different.
Usage
Use meaningful dimensions and a fallback appropriate to the content.
API reference
Generated from the public TypeScript declarations. Native HTML attributes are inherited where the component extends them; this reference includes Pimolu props and selected common native attributes.
PimoluImageProps
Type source| Name | Type | Default | Description |
|---|---|---|---|
srcRequired | string | — | Image URL. |
altRequired | string | — | Accessible alternative. Required by the type on purpose: a decorative image should opt in explicitly with `alt=""`. |
fallbackSrc | string | undefined | — | Second URL tried when `src` fails, before showing the fallback. A failed fallback also ends in the fallback state. |
fallback | ReactNode | — | Custom content shown when the image cannot be displayed. |
fit | PimoluImageFit | undefined | "cover" | How the image fills its box. Defaults to "cover". |
rounded | PimoluImageRounded | undefined | "md" | Corner radius, using the shared radius tokens. Defaults to "md". |
aspectRatio | string | number | undefined | — | Reserves the image box before it loads: a number (`16 / 9`) or a CSS string (`"16 / 9"`). Without it the intrinsic `width`/`height` keep the native aspect ratio and still avoid a layout shift. |
showSkeleton | boolean | undefined | true | Shows the animated placeholder while loading. Defaults to true. |
containerClassName | string | undefined | — | Class applied to the wrapping element. |
containerStyle | CSSProperties | undefined | — | Style applied to the wrapping element. |
onLoad | ((event: SyntheticEvent<HTMLImageElement>) => void) | undefined | — | Called after the active source loads. |
onError | ((event: SyntheticEvent<HTMLImageElement>) => void) | undefined | — | Called whenever a source fails, including the fallback source. |
onChange | ChangeEventHandler<HTMLImageElement, Element> | undefined | — | Standard React/HTML attribute. |
defaultValue | string | number | readonly string[] | undefined | — | Standard React/HTML attribute. |
className | string | undefined | — | Standard React/HTML attribute. |
style | CSSProperties | undefined | — | Standard React/HTML attribute. |
aria-label | string | undefined | — | Defines a string value that labels the current element. |
onClick | MouseEventHandler<HTMLImageElement> | undefined | — | Standard React/HTML attribute. |
srcRequiredstringNo default extracted.
Image URL.
altRequiredstringNo default extracted.
Accessible alternative. Required by the type on purpose: a decorative image should opt in explicitly with `alt=""`.
fallbackSrcstring | undefinedNo default extracted.
Second URL tried when `src` fails, before showing the fallback. A failed fallback also ends in the fallback state.
fallbackReactNodeNo default extracted.
Custom content shown when the image cannot be displayed.
fitPimoluImageFit | undefinedDefault: "cover"
How the image fills its box. Defaults to "cover".
roundedPimoluImageRounded | undefinedDefault: "md"
Corner radius, using the shared radius tokens. Defaults to "md".
aspectRatiostring | number | undefinedNo default extracted.
Reserves the image box before it loads: a number (`16 / 9`) or a CSS string (`"16 / 9"`). Without it the intrinsic `width`/`height` keep the native aspect ratio and still avoid a layout shift.
showSkeletonboolean | undefinedDefault: true
Shows the animated placeholder while loading. Defaults to true.
containerClassNamestring | undefinedNo default extracted.
Class applied to the wrapping element.
containerStyleCSSProperties | undefinedNo default extracted.
Style applied to the wrapping element.
onLoad((event: SyntheticEvent<HTMLImageElement>) => void) | undefinedNo default extracted.
Called after the active source loads.
onError((event: SyntheticEvent<HTMLImageElement>) => void) | undefinedNo default extracted.
Called whenever a source fails, including the fallback source.
onChangeChangeEventHandler<HTMLImageElement, Element> | undefinedNo default extracted.
Standard React/HTML attribute.
defaultValuestring | number | readonly string[] | undefinedNo default extracted.
Standard React/HTML attribute.
classNamestring | undefinedNo default extracted.
Standard React/HTML attribute.
styleCSSProperties | undefinedNo default extracted.
Standard React/HTML attribute.
aria-labelstring | undefinedNo default extracted.
Defines a string value that labels the current element.
onClickMouseEventHandler<HTMLImageElement> | undefinedNo default extracted.
Standard React/HTML attribute.
Accessibility
- Write alternative text for informative imagery and avoid repeating adjacent text unnecessarily.