@tylermcrobert/svelte-sanity-image v1.0.1
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
4 months ago
5 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago