Data Display

Image

Responsive image wrapper that handles aspect ratio, lazy loading, placeholder, and a fallback for load failures.

import { Image } from '@lostgradient/cinder/image';
imagemedia
01

Overview

Responsive image wrapper with aspect-ratio preservation, lazy loading, and fallback support.

Usage

svelte 
<script lang="ts">
  import Image from '@lostgradient/cinder/image';
</script>

<Image />
Live preview
02

When to use

Use when
  • Rendering content imagery with a consistent ratio and lazy-loading behavior.
  • Supplying a placeholder while loading and a fallback when the source errors.
Avoid when
  • Representing a person or account — use avatar instead.
  • Rendering a decorative icon — use an icon component instead.
03

Examples

Basic image

Responsive image with lazy loading and an explicit aspect ratio.

04

Props

Props for image
Name Type Default Required Bindable Description
src text req Image source URL.
alt text req Alternative text. Required with no default — pass alt="" explicitly for decorative images so the choice is intentional, not silent.
width number Native pixel width.
height number Native pixel height.
ratio text CSS aspect-ratio applied to the wrapper (e.g. '16 / 9') so layout is stable while the image loads.
loading 'lazy' | 'eager' 'lazy' Loading strategy. Default lazy. Override to eager for above-the-fold images.
decoding 'async' | 'sync' | 'auto' 'async' Decoding hint. Default async.
placeholder text Low-resolution image source (typically a base64 data URI) shown as a pixelated background while the main image loads. Fades out once the <img> fires load.
fallback snippet Rendered in place of the <img> when it fails to load.
onLoad (event: Event) => void Forwarded after internal state updates.
onError (event: Event) => void Forwarded after internal state updates.