Data Display

Image

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

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

Overview

Reference usage

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

Usage

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

<Image
  src="https://picsum.photos/seed/cinder/600/338"
  alt="A randomly selected placeholder photograph"
  ratio="16/9"
  width={600}
  height={338}
/>

Fit and size

fit (contain, cover, fill, none, scale-down) sets object-fit; omitted, the image covers its box. size (icon, avatar, small, medium, large, header) sets token-based dimensions: icon and avatar are squares, small, medium, and large set the width, and header spans its container at a banner height. Omitted, the image keeps its container-driven size.

svelte 
<Image src="/logo.png" alt="Logo" size="avatar" fit="contain" />
Live preview

Basic image

An illustration of mountains beneath a sun

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
Description
src required text Image source URL.
alt required text 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.
fit 'contain''cover''fill''none''scale-down' How the image fills its box, mapped onto CSS object-fit. Omitted, the image covers the box (cover).
size 'icon''avatar''small''medium''large''header' Token-based dimensions. icon and avatar are squares; small, medium, and large set the width and let ratio or the image's own proportions set the height; header spans the container at a banner height. Omitted, the image keeps its natural, container-driven size.
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.