Media

Image

An image that holds its space while it loads, arrives out of a soft blur, says so when it can't load, and can open larger.

Installation

npx sinaui add image

Copy src/lib/ui/Image.svelte, with Icon.svelte, motion.ts, spring.ts and tokens.css. No dependencies.

Examples

With a placeholder and caption

Give width and height (or ratio) so the page doesn't shift when it arrives. The placeholder color shows until then.

<script lang="ts">
	import Image from '#lib/ui/Image.svelte';
</script>

<div class="demo">
	<Image
		src="https://upload.wikimedia.org/wikipedia/commons/thumb/a/a9/A_Library_in_Golden_Islamic_Age.jpg/960px-A_Library_in_Golden_Islamic_Age.jpg"
		alt="Scholars reading in a library in Basra, books stacked on shelves behind them"
		width={960}
		height={1280}
		ratio="4 / 3"
		placeholder="#c9b48a"
		caption="A library in Basra, from al-Wasiti's Maqamat of al-Hariri, 1237."
	/>
</div>

<style>
	.demo {
		inline-size: min(28rem, 100%);
	}
</style>

Open larger

Press the image: a larger file grows out of it. Escape, the close button or a press anywhere puts it back.

<script lang="ts">
	import Image from '#lib/ui/Image.svelte';
</script>

<div class="demo">
	<Image
		src="https://upload.wikimedia.org/wikipedia/commons/thumb/a/a9/A_Library_in_Golden_Islamic_Age.jpg/960px-A_Library_in_Golden_Islamic_Age.jpg"
		zoom="https://upload.wikimedia.org/wikipedia/commons/thumb/a/a9/A_Library_in_Golden_Islamic_Age.jpg/1280px-A_Library_in_Golden_Islamic_Age.jpg"
		alt="Scholars reading in a library in Basra, books stacked on shelves behind them"
		width={960}
		height={1280}
		ratio="1"
		placeholder="#c9b48a"
	/>
</div>

<style>
	.demo {
		inline-size: min(18rem, 100%);
	}
</style>

When it can't load

The space stays, with the description in place of the picture.

A page from the Book of Ingenious Devices

<script lang="ts">
	import Image from '#lib/ui/Image.svelte';
</script>

<div class="demo">
	<Image
		src="https://example.invalid/kitab-al-hiyal.jpg"
		alt="A page from the Book of Ingenious Devices"
		ratio="4 / 3"
	/>
</div>

<style>
	.demo {
		inline-size: min(20rem, 100%);
	}
</style>

Props

Prop	Type	Default
`src`	`string` (required)
`alt`	`string` (required): what it shows; `""` for decoration
`width`, `height`	`number`
`ratio`	`string`, e.g. `"4 / 3"`	width / height
`fit`	`'cover' \| 'contain'`	`'cover'`
`placeholder`	a color, or a tiny image as a data URL
`caption`	`string`
`zoom`	`boolean \| string`: a larger file's address	`false`
`loading`	`'lazy' \| 'eager'`	`'lazy'`

Other attributes (srcset, sizes) go to the <img>.

Keyboard

Key	Does
`Enter` `Space`	Open the larger view
`Escape`	Close it

Accessibility

With zoom, the image is a button named "Enlarge" plus its description.
The larger view is a modal: focus stays inside until it closes.
An image that fails keeps its description, read out in its place.
With reduced motion, images fade in without blur and the larger view opens in place.