Responsive Image

Material Design 3 responsive image with lazy loading, art direction, loading states, and graceful error handling. Not intended for purely decorative backgrounds that belong in CSS.

Basic Usage

Render a responsive image with source and alt text. The component handles loading states and aspect ratio to reduce layout shift.

<ds-responsive-image
  src="image.jpg"
  alt="Mountain landscape"
  aspect-ratio="4/3">
</ds-responsive-image>

Initial Value

Configure fit and ratio at initialization time.

<ds-responsive-image
  src="image.jpg"
  alt="City skyline"
  aspect-ratio="16/9"
  fit="contain">
</ds-responsive-image>

Variants

Choose fit mode and source strategy based on layout needs.

Object Fit Modes

Picture Sources

States

Support lazy loading and error display states.

Interactive Example

Adjust fit and aspect ratio to preview responsive behavior.

Aspect Ratio Object Fit

Event log:

API

Attributes

Attribute	Type	Default	Description
`src`	string	""	Main image URL.
`srcset`	string	""	Responsive source set string.
`sizes`	string	""	Sizes descriptor for srcset selection.
`alt`	string	""	Alternative text for accessibility.
`lazy`	boolean	false	Enable lazy loading with IntersectionObserver.
`aspect-ratio`	string	`auto`	Container aspect ratio (e.g. `16/9`).
`fit`	string	`cover`	`cover`, `contain`, `fill`, `scale-down`, `none`.

Properties

Property	Type	Description
`src`	string	Source URL.
`srcset`	string	Source set value.
`sizes`	string	Sizes descriptor.
`alt`	string	Alternative text.
`lazy`	boolean	Lazy loading toggle.
`aspectRatio`	string	Aspect ratio mapping to `aspect-ratio`.
`fit`	string	Object fit mode.
`loaded`	boolean	Read-only loaded state.
`error`	boolean	Read-only error state.

Events

Event	Detail	Description
`image-loading`	`{ src }`	Fired when loading starts.
`image-loaded`	`{ src }`	Fired when image loads successfully.
`image-error`	`{ src }`	Fired when image fails to load.

Methods

Method	Description
`reload()`	Resets state and retries current image load.

CSS Parts

Part	Description
None	This component currently does not expose shadow parts.

CSS Custom Properties

Property	Description
`--ds-responsive-image-loading-padding`	Error/loading content padding (default `var(--ds-space-4)`).
`--ds-responsive-image-loading-gap`	Gap in placeholder layout (default `var(--ds-space-2)`).
`--ds-responsive-image-icon-size`	Placeholder/error icon size (default `var(--ds-size-icon-lg)`).

Accessibility

Always provide meaningful alt text for non-decorative images.
Image element keeps semantic role="img".
Error state exposes readable text fallback.
Use external captions for additional context where needed.

Usage Guidelines

Use aspect-ratio to reduce layout shift during loading.
Prefer lazy for below-the-fold images.
Use srcset and sizes for bandwidth-efficient responsive images.
Choose fit="cover" for media crops and fit="contain" when full content must remain visible.