Image

Wrapper over <img> with sizing helpers (full, cover) and the ImageLazy variant that defers loading until the image enters the viewport.

When to use

✅ Use when…	🚫 Avoid when…
For any content image (covers, thumbnails, illustrations). In long lists, prefer `ImageLazy` to reduce bandwidth and improve LCP. When you need to fill a container with the image cropping the overflow, use `cover`.	As a circular avatar — use `Avatar`. For the design system's vector icons — use `Icon` or `Svg`. For decorative background content. Apply `background-image` on the container directly.

Basic usage

import { Image } from '@apollion-dsi/core/elements/image';
 
const Example = () => <Image width={400} height={237} src="https://picsum.photos/400/237/" />;

width/height are forwarded to the DOM as native <img> HTML attributes (in addition to driving the CSS) — they reserve space in the layout and prevent CLS. Always pass both when you know the image's dimensions.

Image `cover`

The image fills the whole container space preserving aspect ratio (crops the overflow).

<Paper height={150} borderRadius="large" overflow="hidden" deep={0}>
  <Image cover src="https://picsum.photos/500?random=2" />
</Paper>

ImageLazy

ImageLazy has the same API as Image adding threshold — a value from 0 to 1 that defines how much of the component needs to be visible to trigger the download.

import { ImageLazy } from '@apollion-dsi/core/elements/image';
 
const Example = () => <ImageLazy width={400} height={237} threshold={0.5} src="https://picsum.photos/400/237/" />;

Properties


Prop	Type	Default	Description
`cover`	`boolean`	`false`	Applies `object-fit: cover` with 100% width/height, filling the container and cropping the overflow. Useful for banners, covers, and thumbnails.
`fallback`	`Element`	—	Element displayed while the image loads. Used by `ImageLazy` — ignored by the direct `Image`.
`full`	`boolean`	`false`	Makes the image take up 100% of the container's width.

Besides the props above, every component accepts the layout props (spacing, color, flex/grid, sizing, border) — not repeated here.