Image

SImage shows a picture with lazy loading, a placeholder while it loads and a fallback when it fails. alt is required: without a text alternative the image is silent to a screen reader and leaves nothing behind when the request fails — a purely decorative picture passes an empty string.

ratio wraps the picture in SAspectRatio, so the frame reserves its height before the file arrives and the layout does not jump. Without ratio the frame is sized by your own CSS. fit and position map to object-fit/object-position, and square removes the border radius. Changing src starts over: the placeholder comes back for the new picture.

Basic usage

<template>
  <SImage
    src="/photos/hills.jpg"
    alt="Sunlit hills under a clear sky"
    :ratio="16 / 9"
  />
</template>

Fit and position

fit decides what happens when the picture and the frame have different proportions: cover crops it, contain fits the whole picture inside, fill stretches it. position moves the visible part of a cropped picture ('top', '50% 20%').

<template>
  <SImage
    src="/photos/portrait.jpg"
    alt="Portrait cropped to a square"
    :ratio="1"
    fit="cover"
    position="top"
  />
  <SImage
    src="/photos/portrait.jpg"
    alt="Whole portrait inside a square"
    :ratio="1"
    fit="contain"
  />
  <SImage
    src="/photos/portrait.jpg"
    alt="Portrait stretched to a square"
    :ratio="1"
    fit="fill"
  />
</template>

Loading placeholder

A skeleton fills the frame until the picture is decoded and disappears on load as well as on error. Turn it off with :placeholder="false", or put your own content in the placeholder slot — a blurred thumbnail, a dominant colour, a logo. Images below the fold load lazily by default; pass :lazy="false" for the one at the top of the page, so the browser requests it straight away.

<template>
  <SImage
    src="/photos/hero.jpg"
    alt="Hero picture"
    :ratio="16 / 9"
    :lazy="false"
  >
    <template #placeholder>
      <div class="hero-blur" />
    </template>
  </SImage>
</template>

Error fallback

When src fails, fallback is requested instead. Without it the frame keeps a muted surface that carries alt as its accessible name, and the error slot replaces that surface with your own message. Both load and error are also emitted, so the page can react — log the miss, hide the block, ask for another source.

<script setup lang="ts">
function reportMissingPhoto() {
  // send the miss to your analytics
}
</script>

<template>
  <SImage
    src="/photos/product.jpg"
    alt="Product photo"
    :ratio="4 / 3"
    fallback="/photos/placeholder.svg"
  />
  <SImage
    src="/photos/product.jpg"
    alt="Product photo"
    :ratio="4 / 3"
    @error="reportMissingPhoto"
  >
    <template #error>
      <span class="photo-missing">Photo unavailable</span>
    </template>
  </SImage>
</template>

API

Props

Name	Type	Default	Description
src*	string	required	Image URL.
alt*	string	required	Text alternative. Required: an image without one is silent to a screen reader and leaves nothing behind when it fails to load. A purely decorative image passes an empty string.
srcset	string	undefined	Candidate sources for a responsive image — the srcset attribute.
sizes	string	undefined	Slot widths the browser picks srcset candidates by — the sizes attribute.
ratio	number	undefined	Aspect ratio of the frame (width / height, e.g. 16 / 9). The image is wrapped in SAspectRatio, so the frame keeps its height and the layout does not jump while loading. Without it the frame is sized by the consumer's own CSS.
fit	| "fill" | "none" | "cover" | "contain" | "scale-down"	"cover"	How the image fills the frame — the object-fit value.
position	string	"center"	Which part of the image stays in view when it is cropped — the object-position value ('center', 'top', '50% 20%').
lazy	boolean	true	Defers the request until the image nears the viewport (loading="lazy" plus asynchronous decoding). Turn it off for an image above the fold.
placeholder	boolean	true	Shows a skeleton while the image loads; it goes away both on success and on failure. The placeholder slot replaces the skeleton.
fallback	string	undefined	URL loaded instead of src after src fails. Without it a failure shows the error slot, or a muted surface when that slot is empty.
square	boolean	undefined	Square corners: removes the border radius (rounded by default).

Events

Name	Signature	Description
error	(event: Event) => void	The image failed to load; fires again when the fallback fails as well.
load	(event: Event) => void	The image finished loading.

Slots

Name	Description
placeholder	Replaces the loading skeleton.
error	Replaces the surface shown once the image — and the fallback — failed to load.