Image
Shows an image at a set ratio and fit, with a placeholder when the source is missing or fails to load. Overlays such as a scrim or gradient can sit on top.
// Plain markup
import { Image } from "@shavin/ui";Placeholder (no source)
Component Source
{/* No src → a graceful placeholder, sized by ratio */}
<Image ratio="16/9" className="w-64" />With a source

Component Source
<Image src="/hero.jpg" alt="Hero" ratio="16/9" className="w-64" />Aspect ratios



Component Source
<Image ratio="1/1" className="w-32" />
<Image ratio="4/3" className="w-32" />
<Image ratio="16/9" className="w-32" />Fit


Component Source
{/* object-fit: cover (default) vs contain */}
<Image src="/tall.jpg" fit="cover" ratio="1/1" className="w-32" />
<Image src="/tall.jpg" fit="contain" ratio="1/1" className="w-32" />Radius




Component Source
<Image radius="none" ratio="1/1" className="w-24" />
<Image radius="medium" ratio="1/1" className="w-24" />
<Image radius="large" ratio="1/1" className="w-24" />
<Image radius="full" ratio="1/1" className="w-24" />Concentric radius

Component Source
{/* radius="concentric" auto-resolves the inner
radius from the container's padding */}
<Card padding="md">
<Image src="/hero.jpg" alt="Hero" ratio="16/9" radius="concentric" />
</Card>Overlays


Component Source
{/* bgOverlays composites layers on top — same system layouts use.
Presets ("scrim"), gradients, solids, or an fx effect. */}
<Image src="/hero.jpg" alt="Hero" ratio="16/9" bgOverlays="scrim" className="w-64" />
<Image src="/hero.jpg" alt="Hero" ratio="16/9" bgOverlays="gradient-bottom, dark-20" className="w-64" />Broken source → placeholder

Component Source
{/* Broken / invalid src → gracefully falls back to SVG placeholder */}
<Image src="/does-not-exist.jpg" alt="Missing" ratio="16/9" className="w-64" />Props
| Prop | Type | Default | Description |
|---|---|---|---|
| src | string | — | Image source URL. |
| alt | string | — | Image accessible alt text. |
| ratio | string | — | CSS aspect-ratio string, e.g. "16/9", "1/1", "4/3". Reserves space to avoid layout shift. |
| fit | "cover" | "contain" | "fill" | "none" | cover | Object fit style: "cover", "contain", "fill", "none". Default "cover". |
| placeholder | React.ReactNode | — | Custom placeholder node shown when src is missing or fails to load. |
| bgOverlays | string | — | Overlay layers composited on top of the image (scrim / gradient / solid / fx), same shorthand + JSON format as a layout's bgOverlays — one unified layer system. |
| radius | "none" | "small" | "medium" | "large" | "full" | "inherit" | "concentric" | "inherit" | — |