Image

A responsive <picture>/<img> wrapper with lazy loading, placeholder, and load/error state styling.

Usage

Use standalone.

Svelte

<Image src="/photo.jpg" alt="Photo" />

Anatomy

The class attribute values represent part names, and conditional indicates elements that are rendered conditionally. Other attributes represent their corresponding props.

Svelte

<picture class="whole">
  <source srcset type media sizes width height conditional:sources />
  <img class="main" {...rest} {src} {alt} loading fetchpriority decoding style onload onerror data-loaded data-error />
</picture>

Props

Name	Type	Default	Description
`src*`	`string`	-	Image source for the inner `<img>`
`alt*`	`string`	-	Alternative text; empty string is valid for decorative images
`sources`	`ImageSource[]`	-	Alternate `<source>` candidates for the root `<picture>`
`placeholder`	`string`	-	CSS background shown on the image until it loads
`firstView`	`boolean`	`false`	Sets eager loading, high fetch priority, and default preload unless native attributes override it
`preload`	`boolean`	`firstView ?? false`	Adds a preload link for the highest-priority candidate
`onload`	`EventHandler`	-	Load handler on the inner `<img>`
`onerror`	`EventHandler`	-	Error handler on the inner `<img>`
`attach`	`Attachment`	-	Svelte attachment on the inner `<img>`
`element`	`HTMLImageElement`	-	Bindable inner image element
`styling`	`SVSClass`	-	Styling override
`variant`	`SVSVariant`	`NEUTRAL`	Bindable variant

* required. Other HTMLImgAttributes are passed to <img> via rest props; class is merged onto the root <picture>.

Supply both width and height when possible to reserve aspect ratio and minimize layout shift.

Styling

To learn more, see Styling.

Variant Management

The caller's variant is used in the neutral state until load. Successful load sets data-loaded and switches to active; load error sets data-error and switches to inactive. When src changes, the load state resets and the caller's variant is restored.

Default Class Name

svs-image

Behavior

firstView is sugar for eager loading, high fetch priority, and preload; native loading, fetchpriority, and decoding attrs in ...rest override the defaults. Load sets data-loaded and variant=ACTIVE; error sets data-error and variant=INACTIVE; neutral state restores the caller's variant. A placeholder is emitted as the img background until load, then cleared. Missing <source> types are derived from the first srcset candidate's extension when known. Preload mirrors only the highest-priority candidate (sources[0] or the img), so art-direction fan-out is intentionally represented by a single preload link.

Exports

Types

TypeScript

interface ImageSource {
  srcset: string;
  type?: string;
  media?: string;
  sizes?: string;
  width?: number;
  height?: number;
}
interface ImageProps extends Omit<HTMLImgAttributes, "src" | "alt" | "onload" | "onerror"> {
  src: string;
  alt: string; // empty string is valid for decorative images
  sources?: ImageSource[]; // alternate <source> candidates
  placeholder?: string; // CSS background shown until load
  firstView?: boolean; // (false); sets eager/high/default preload unless overridden
  preload?: boolean; // (firstView ?? false)
  onload?: EventHandler<Event, HTMLImageElement> | null;
  onerror?: EventHandler<Event, HTMLImageElement> | null;
  attach?: Attachment<HTMLImageElement>;
  element?: HTMLImageElement; // bindable
  styling?: SVSClass;
  variant?: SVSVariant; // bindable (VARIANT.NEUTRAL)
  // other HTMLImgAttributes are passed to <img> via ...rest; `class` is merged onto root <picture>
}
type ImageReqdProps = "src" | "alt";
type ImageBindProps = "element" | "variant";

Others

No additional exports are available.

Examples

The example code uses Tailwind CSS along with SVSClass.

Basic

Load & Error States

Loaded

Error