Image
Responsive images with fitting, aspect ratios, rounded corners, overlays, loading and fallback states.
Image wraps a native <img> with token-based presentation and resilient loading/error states.
Basic usage and fitting
alt remains required for accessible image content. fit maps to CSS object-fit: cover, contain, fill, none or scale-down.
<Image src="/hero.jpg" alt="A mountain landscape" />
<Image src="/logo.svg" alt="Company logo" fit="contain" />Shape, ratio and overlay
radius accepts none, sm, default, lg or full. aspectRatio accepts a number or CSS ratio string such as 16 / 9. bordered adds a token border. overlay renders content over the image and can be positioned at top, center or bottom.
<Image src="/cover.jpg" alt="Cover" aspectRatio="16 / 9" radius="lg" overlay="View project" overlayPosition="bottom" />Common aspect ratios include 1 / 1 for square images, 3 / 4 for portraits, 4 / 3 for standard landscape media and 16 / 9 for widescreen media. The ratio controls the wrapper; use style, className or a CSS width to control its size.
Hover and interaction
Images zoom smoothly by 1.08 on hover by default. Use hoverScale to control the zoom ratio and hoverDuration to control the transition speed in milliseconds. Set disableHover to remove the zoom. Providing onClick makes the image interactive: it receives a pointer cursor, focus styling and button-like Enter/Space keyboard activation.
<Image src="/cover.jpg" alt="Cover" aspectRatio="16 / 9" onClick={openPreview} />
<Image src="/cover.jpg" alt="Static cover" disableHover />
<Image src="/cover.jpg" alt="Strong hover" hoverScale={1.16} hoverDuration={420} />Loading and fallback
The component shows a loader while the image is loading when showLoader is true (the default). When loading fails, fallback replaces the image. onLoad and onError are called in addition to the internal state handling.
If src is missing, the fallback content is rendered immediately. Native image attributes such as loading, decoding, srcSet, sizes, crossOrigin and referrerPolicy are passed to the underlying <img> element. className styles the wrapper; imageClassName styles the native image itself; style styles the wrapper and can set its width or height.
API Reference
| Prop | Values | Default | Description |
|---|---|---|---|
src, alt | native image props | — | Image source and alternative text. alt should describe meaningful images; use an empty value for decorative images. |
loading, decoding, srcSet, sizes | native image props | browser defaults | Native loading, decoding and responsive source settings. |
fit | contain | cover | fill | none | scale-down | cover | Object fitting mode. |
radius | none | sm | default | lg | full | default | Corner radius. |
aspectRatio | number | string | — | Wrapper aspect ratio. |
bordered | boolean | false | Adds a border. |
disableHover | boolean | false | Disables the hover zoom. |
hoverScale | number | 1.08 | Scale applied to the image on hover. Values below 1 are normalized to 1. |
hoverDuration | number | string | 220 ms | CSS transition duration; numbers are interpreted as milliseconds. |
onClick | function | — | Makes the image interactive with pointer and keyboard activation. |
overlay | ReactNode | — | Content layered above the image. |
overlayPosition | top | center | bottom | center | Overlay alignment. |
showLoader | boolean | true | Shows loading indicator. |
fallback | ReactNode | Image unavailable | Error-state content. |
className | string | — | Class for the wrapper. |
imageClassName | string | — | Class for the native image element. |
style | CSSProperties | — | Inline styles for the wrapper, including dimensions. |
onLoad | image load handler | — | Called after the image loads successfully. |
onError | image error handler | — | Called when loading fails. |