Documentation

Documentation

Image

Responsive image with aspect presets, lazy loading, and a fallback and error state.

The <dsgn-image> component wraps a native <img> with aspect-ratio presets, object-fit control, corner radius, and a built-in failure path: a fallback source, then a slotted or default error state.

Usage

<dsgn-image src="/images/hero.jpg" alt="Hero banner" aspect="video"></dsgn-image>

Import the component module in your application entrypoint:

import '@ds-gn/ui/image';

Props

Prop Type Default Description
src string '' Image source URL. With no src, the component renders the fallback or error state.
alt string '' Alternative text. Leave empty for decorative images.
fit 'cover' | 'contain' | 'fill' | 'none' | 'scale-down' 'cover' CSS object-fit behavior.
aspect 'auto' | 'square' | 'video' | 'photo' | 'portrait' | 'wide' 'auto' Aspect-ratio preset for the wrapper.
radius 'none' | 'sm' | 'md' | 'lg' | 'xl' | 'full' 'none' Corner radius.
loading 'lazy' | 'eager' 'lazy' Native loading strategy.
srcset string '' Responsive srcset passed to the <img>.
sizes string '' Responsive sizes passed to the <img>.
width number undefined Intrinsic width, to reserve space and avoid layout shift.
height number undefined Intrinsic height, to reserve space and avoid layout shift.
fetchpriority string '' Fetch-priority hint on the <img>. Use high for an above-the-fold image.
fallback-src string '' Image to show when the primary source fails.
surface 'light' | 'dark' 'light' Semantic token surface to use.

The prop is fit, not object-fit. fallback-src is the attribute name; the matching JavaScript property is fallbackSrc. width and height are numbers.

Slots

Slot Description
error Custom content displayed when the image cannot be loaded.

Events

Event Detail Description
dsgn-image-error { src } Fired when the image fails to load. Bubbles and crosses the shadow boundary.

In React, the generated wrapper exposes this as onDsgnImageError.

Failure behavior

  1. If src is empty or the image errors, the component looks for fallback-src and renders that image instead.
  2. With no fallback, it renders the error state: your error slot content, or a default broken-image glyph.
  3. Setting a new src clears the error state and retries.

The error container takes role="img" and the alt text when alt is set, and role="presentation" when it is empty — so a decorative image stays silent even when it fails.

Examples

Aspect presets

<dsgn-image src="/photo.jpg" alt="Square crop" aspect="square"></dsgn-image>
<dsgn-image src="/photo.jpg" alt="16:9 crop" aspect="video"></dsgn-image>
<dsgn-image src="/photo.jpg" alt="Portrait crop" aspect="portrait"></dsgn-image>

Above-the-fold hero image

<dsgn-image
  src="/images/hero.jpg"
  alt="Product screenshot"
  loading="eager"
  fetchpriority="high"
  width="1200"
  height="675"
  aspect="video"
></dsgn-image>

Responsive sources

<dsgn-image
  src="/images/photo-800.jpg"
  srcset="/images/photo-800.jpg 800w, /images/photo-1600.jpg 1600w"
  sizes="(min-width: 64rem) 50vw, 100vw"
  alt="A sample photo"
></dsgn-image>

Fallback and custom error content

<dsgn-image
  src="/missing.jpg"
  alt="Avatar"
  fallback-src="/avatar-default.png"
  radius="full"
></dsgn-image>

<dsgn-image src="/missing.jpg" alt="Chart">
  <dsgn-text slot="error" size="sm" color="secondary"
    >Chart unavailable.</dsgn-text
  >
</dsgn-image>

Reacting to a load failure

document
  .querySelector('dsgn-image')
  .addEventListener('dsgn-image-error', (event) => {
    console.warn('image failed', event.detail.src);
  });

Accessibility

  • Give every meaningful image a descriptive alt; leave alt empty for purely decorative images so screen readers skip them.
  • Set width and height (or an aspect preset) to reserve space and avoid layout shift while the image loads.
Esc