Image

Responsive image with skeleton and optional lightbox.

A responsive `<picture>` with `srcset`/`sizes`, lazy + async decoding, an aspect-ratio box that reserves space before load (no layout shift), a token-driven loading skeleton, an error fallback, and an optional lightbox. The lightbox is a lightweight built-in dialog overlay — dssoca depends on no image/lightbox runtime (e.g. PhotoSwipe) and stays zero-runtime-dependency.

Demo

live · storybook Open in Storybook

Demo loads from https://dssoca-storybook.vercel.app/. Run pnpm storybook for it to render locally.

Usage

svelte

<script>
  import { Image } from 'dssoca';
</script>

<!-- Aspect-ratio box reserves space before the image loads -->
<Image src="/photo.jpg" alt="A scenic photo" ratio={16 / 9} />

<!-- Responsive <picture> + click-to-zoom lightbox -->
<Image
  src="/photo-960.jpg"
  alt="A scenic photo"
  width={960}
  height={540}
  sources={[
    { srcset: '/photo.avif', type: 'image/avif' },
    { srcset: '/photo.webp', type: 'image/webp' }
  ]}
  caption="On the trail"
  lightbox
/>

No layout shift: a ratio box (from `ratio`, or derived from `width`/`height`) reserves space before load. Lazy + async by default; flip `eager` for above-the-fold hero images. The loading skeleton respects `prefers-reduced-motion` (the shimmer freezes) and a load error swaps in a labelled fallback. The optional lightbox is a built-in overlay (no PhotoSwipe dependency): `role="dialog"` + `aria-modal`, a focus trap (which skips disabled / `aria-disabled` / `tabindex="-1"` elements), `Esc`/backdrop-click to close, and focus restored to the trigger.

Props

Prop	Type	Default	Description
`src`	`string`	—	Image URL (fallback <img> source).
`alt`	`string`	—	Required alternative text (WCAG 1.1.1). Use "" only for purely decorative images.
`srcset`	`string`	—	Responsive srcset for the fallback <img>.
`sizes`	`string`	—	sizes hint paired with srcset.
`sources`	`ImageSource[]`	`[]`	Responsive <picture> sources: { srcset, media?, type?, sizes? }.
`width`	`number`	—	Intrinsic width (px) — feeds the aspect-ratio box and the img attr.
`height`	`number`	—	Intrinsic height (px) — feeds the aspect-ratio box and the img attr.
`ratio`	`number`	—	Aspect ratio (w / h) to reserve space before load. Wins over width/height.
`fit`	`'cover' \| 'contain' \| 'fill' \| 'none' \| 'scale-down'`	`'cover'`	object-fit inside the reserved ratio box.
`eager`	`boolean`	`false`	Eager-load above-the-fold (loading="eager", decoding="auto", fetchpriority="high").
`lightbox`	`boolean`	`false`	Open the built-in dialog overlay on click (role="dialog", aria-modal, focus trap, Esc to close, restores focus).
`caption`	`string`	—	Caption rendered in a <figcaption> under the image.
`size`	`'sm' \| 'md' \| 'lg'`	—	Per-instance size override; inherits the ancestor `data-size-variant` when unset.