svelte-sanity-image

A Svelte component for creating responsive, optimized images from Sanity.io. Powered by the Sanity Image Builder under the hood, it simplifies responsive image handling and layout shift prevention in your Svelte projects.

✨ Features

• Prevents layout shifts by setting image dimensions automatically.
• Creates srcset attributes for responsive images out of the box.
• Supports custom aspect ratios.
• Provides control of native <img /> attributes.
• Available preloading of images with the preload prop.
• Fully typed with TypeScript support and unit-tested for reliability.

📦 Installation

Install the package via npm:

npm install @tylermcrobert/svelte-sanity-image

🚀 Quick Start

A minimal example of using svelte-sanity-image:

<SanityImage
	{client}
	{image}
	sizes="(max-width: 768px) 50vw, 100vw"
	alt="The Beatles crossing Abbey Road in London."
/>

This component extends the standard <img /> element, so you can use any native attributes or events.

An example creating a wrapper component:

<script lang="ts">
	import { client } from '$lib/sanity';
	import Image, { type SvelteSanityImageProps } from '@tylermcrobert/svelte-sanity-image';

	type ImageProps = Omit<SvelteSanityImageProps, 'client'> & {
		aboveTheFold: boolean;
	};

	let { aboveTheFold, ...props }: ImageProps = $props();
</script>

<Image
	{...props}
	{client}
	quality={80}
	loading={aboveTheFold ? 'eager' : 'lazy'}
	fetchpriority={aboveTheFold ? 'high' : undefined}
/>

An example using getImageProps:

<script lang="ts">
	import { client } from '$lib/sanity';
	import Image, { type getImageProps } from '@tylermcrobert/svelte-sanity-image';

	type ImageProps = { image: SanityImageSource };

	let { image }: ImageProps = $props();

	let imageProps = $derived(getImageProps(client, image, { quality: 80 }));
</script>

<img {...imageProps} />

⚙️ Component Props

| Property | Type | Description | Required | | ------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | client | Object | A configured Sanity client or project details. | Yes | | image | Object | Image data returned from Sanity API. | Yes | | alt | String | Descriptive alt text for accessibility. | Yes | | sizes | String | null | A responsive image size string (MDN reference). Set to null to bypass responsivity. | Yes | | aspect | Number | Enforces an aspect ratio on the image. | – | | preload | Boolean | Adds a <link rel="preload" /> in <svelte:head> for prioritized loading. | – | | srcsetBreakpoints | string[] | Overrides the default breakpoints for srcset. Defaults to 640, 750, 828, 1080, 1200, 1920, 2048, 3840. | – |

Optimization Defaults

This package makes similar default optimizations as Next/Image.

| Property | Value | Description | | ------------ | ------ | ----------------------------------------------------------------------------------------------------------------------- | | loading | lazy | Defers loading of images until they are near the viewport. | | autoFormat | true | Automatically return an image in the most optimized format supported by the browser as determined by its Accept header. | | quality | 75 | Set automatically to 75 by Sanity`s internal image transformations |

Supported Sanity transformations:

svelte-sanity-image supports the following Image Transformations:

blur, bg, dpr, width, height, quality, sharpen, format, invert, download, flipHorizontal, flipVertical, saturation, and frame.

🤝 Contributing

Go into the package.json and give your package the desired name through the "name" option. Also consider adding a "license" field and point it to a LICENSE file which you can create from a template (one popular option is the MIT license).

📜 License

MIT License © 2024 Tyler McRobert