Skip to main content

Image

Classless responsive image with optional shape, fit, and emphasis values. A plain <img> is responsive by default; the .image mirror class is available for non-<img> elements or when an explicit hook is needed. Composable values control the shape (rounded, circular), the fit behavior (cover, contain, fill), and the emphasis (subtle/neutral/accent, where accent renders a decorative frame).

Usage​

When to use

  • Embedding any raster or vector image inside content
  • When a responsive, fluid image is needed without extra wrapper markup
  • Applying a consistent rounded, circular, or framed-accent treatment to an image across the site

When not to use

  • For images that need a caption - use the figure component instead
  • For decorative background imagery driven by layout - use a CSS background-image on the container
  • For logos - use the logo component so responsive sources and dark-mode swaps are handled consistently

Do

  • Provide a meaningful alt attribute on every <img>
  • Use alt="" for purely decorative images so screen readers skip them
  • Add loading="lazy" on below-the-fold images for performance

Don't

  • Embed text inside images - use real text alongside or a <figure> with <figcaption>
  • Combine shape and emphasis values that visually conflict (e.g. .circle with a heavy .accent frame)

API​

Props​

PropTypeDefaultDescription
srcstring-Image URL.
altstring-Alternative text. Use an empty string for purely decorative images.
loadingEnum: lazy, eager-Browser loading strategy. Omit for default browser behavior.
classesarray-Additional CSS class words merged into the root element.
attributesobject-Additional HTML attributes spread on the root element.

Classes​

ClassCapabilityDefaultDescription
.subtleEmphasis-Lower emphasis; a muted, quieter weight.
.neutralEmphasisYesDefault emphasis; the standard weight at balanced contrast.
.accentEmphasis-Higher emphasis; a stronger, louder weight.
.smSize-Small.
.mdSizeYesMedium.
.lgSize-Large.
.roundedShape-Rounded corners.
.squareShape-Sharp corners.
.pillShape-Fully rounded ends.
.circleShape-Perfect circle.
.coverFit-Content fills the box, cropping overflow (object-fit: cover).
.containFit-Content scales within the box preserving aspect ratio (object-fit: contain).
.fillFit-Content stretches to fill the box, may distort (object-fit: fill).

Examples​

Lazy loading​

loading="lazy" demonstration.

Shapes​

Every shape value side by side, each setting the corner geometry of the same photograph.

Fit​

Every fit value in a fixed frame, so the difference between filling the box and fitting inside it is visible.

Accessibility​

  • WCAG 2.2 AA
  • Every <img> has an alt attribute.
  • Decorative images use alt="" so they are ignored by assistive tech.
  • Text embedded in images is avoided in favor of real text.
  • Color and shape alone never convey meaning - captions live in <figure>.
  • figure - captioned image pattern
  • logo - site logo with responsive sources