Skip to the content

Image

Image wraps a native <img> with display: block and two sizing helpers: full and cover. ImageLazy is the same image, downloaded only when it scrolls into view.
Typography & Media

When to use

Use when
  • You show a content image: cover, thumbnail or illustration.
  • An image must fill its container and crop the overflow (cover).
  • A long list holds many images below the fold (ImageLazy).
Avoid when
  • The image is a user's photo in a circle — use Avatar.
  • The graphic is a design-system icon or a vector — use Icon or Svg.

Usage

Random landscape
import { Image } from '@apollion-dsi/core/elements/image';

<Image width={400} height={237} src="/photo.jpg" alt="Team at the offsite" />;

Numeric width and height also reach the DOM as native <img> attributes, so the browser reserves the space and the layout does not shift. Pass both when you know the image's dimensions. Without them the image keeps its natural size; full stretches it to the container width.

Cover

cover applies object-fit: cover at 100% width and height: the image fills its container and crops the overflow.

<Paper height={150} borderRadius="large" overflow="hidden" deep={0}>
  <Image cover src="/banner.jpg" alt="" />
</Paper>

Lazy loading

ImageLazy takes the same props plus threshold: the fraction of the element, from 0 to 1, that must be visible before the download starts. Until the image loads it shows fallback, or a skeleton sized by width and height.

import { ImageLazy } from '@apollion-dsi/core/elements/image';

<ImageLazy width={400} height={237} threshold={0.5} src="/photo.jpg" alt="Team at the offsite" />;

Accessibility

  • Always pass alt. Describe the content for meaningful images; use alt="" for decorative ones.
  • ImageLazy loads only in the browser, through IntersectionObserver; give the fallback the same size to avoid a layout shift.

Properties

See also